Guide · Diagnosing feed errors
Product feed errors: diagnosis and repair
A product feed error is a statement about one row and one field, not a verdict on your catalog. How to read it, separate blocking requirements from advice, avoid the repairs that make things worse, and prove a fix actually worked.
64 versioned rules across 3 rulesets · ruleset 1.0.0 · rule data verified 11 November 2026 · no account needed for a local run
Blocking rules
46 report an error when they fail
Advisory rules
4 report a warning
Review rules
9 ask for a human decision
Ruleset version
1.0.0
1. An error is a statement about one row and one field
Product feed errors read like account verdicts but almost never are. A Merchant Center message such as “invalid value” for an image refers to a specific item, a specific attribute, and a specific value in the file. Before changing anything, find three things in the message: which item, which field, and what the platform compares the value against.
The failure to avoid is the shotgun repair: rewriting the whole catalog after one rejection message. That destroys the ability to tell which change fixed the problem, and it is how good data in unaffected rows gets corrupted.
2. Separate blocking requirements from advice
Blocking (error)
A required field is missing or malformed, an enum value is unsupported, a URL is not absolute, an image is below the applicable minimum. These are deterministic: given the data and a date, the verdict is the same for everyone.
Advisory (warning)
A recommendation was not followed, or a future requirement is approaching. Doing nothing is legitimate; knowing about it is the point. A warning must never be reported as an error, or merchants learn to ignore both.
Needs review
The evidence cannot settle it: an ambiguous price, a category that decides which threshold applies, a page that only renders with JavaScript. The honest answer is “a human must decide”, not a coin flip dressed as a verdict.
3. The error classes that actually repeat
- Identifiers. Duplicate item IDs across rows; a blank ID where the destination requires uniqueness; a GTIN with a wrong check digit. The trap is “fixing” a missing GTIN by inventing one — that is worse than omitting it.
- Money. A price with a grouping comma, a currency symbol instead of an ISO code, a sale price above the regular price, or currency inferred from a symbol. Each of these fails deterministically and each has an obvious correct form.
- URLs. A protocol-relative URL, a relative path, a URL with embedded credentials, or a URL that answers 200 with an HTML error page. Only the last needs a remote check to notice.
- Availability. An unsupported enum spelling, or a preorder/backorder value without the availability date the destination requires.
- Images. A file below the applicable minimum, in a format that is not accepted, above the size limit, animated, or undecodable. The minimum depends on the date, which is why a stale mental model produces the wrong fix.
- Variants. A group ID equal to an item ID, variant flags missing on rows that are variants, or per-variant details copy-pasted from the parent so two variants claim the same price and URL.
- Content. A title or description above the published maximum. Truncation by the platform is not the same as a shorter title you control.
4. Read the raw value before you edit it
Most destructive repairs start with a reasonable guess about what the value was. Look at the raw source value first, then at the normalized value a checker used. A difference between the two is where an import bug hides: a leading zero lost to a spreadsheet, a 13-digit GTIN turned into scientific notation, a non-breaking space at the end of a brand name, a currency code stripped by a column rename.
This is why the checker keeps the original row and the normalized value side by side, and why an export preserves columns it did not touch. If a repair changes a field outside the intended fix, the tool refuses to export rather than shipping a change you did not review.
5. What must never be invented
- A GTIN, MPN or any manufacturer identifier. A generated identifier can collide with a real product, which is a worse outcome than a missing field.
- A brand name, a seller name, or a category.
- A price, a sale price, or a currency. A price the merchant did not set is a commercial and legal problem, not a data problem.
- A stock or availability value. Claiming in stock when stock is unknown causes cancellations.
- A replacement image URL. A placeholder passes the URL check and fails the product check.
These are the reasons the MVP only offers deterministic repairs. Everything else is guidance: the exact field, the exact rule, the exact source, and a request to supply the real value from the source system.
6. Prove the fix worked
- Re-import the repaired file and re-run the same ruleset version.
- Compare issues by (rule, product, field) — not by counting. A run with the same number of issues can still have fixed five and introduced five.
- Label each issue: Resolved (was there, gone now), Persisting (still there), New (did not exist before), Changed (same rule and product, different raw value or evidence).
- If the ruleset version changed between runs, treat the comparison as cross-version and show the rule versions side by side, because a rule change can manufacture “new” issues without any file change.
- Keep the original file. The repair is reversible only while the source is intact.
Counting is the trap: “from 412 errors to 398” says nothing about whether the same rows are involved, and a repair that fixes one issue while breaking another nets out to zero.
7. What no checker can tell you
- Whether the platform will accept the item. Approval involves account state, policy review and data outside the file.
- Whether a page renders correctly for a person. Static HTML evidence is all that is used; JavaScript-only pages become Needs review.
- Whether a category-specific rule applies when the category is unknown.
- Whether an identifier is genuine. Length and check digit are checkable; ownership is not.
- Whether your images are policy-compliant. Overlays, watermarks and placeholders need eyes.
8. A workable order of operations
- Parse and structure first. Fix the file format, duplicate headers and encoding before diagnosing any rule — every downstream verdict depends on the rows being read correctly.
- Then identifiers and money, because those are cheap to verify and expensive to get wrong.
- Then URLs, then images, then variants, then content.
- Only then opt in to remote checks, and only for the URLs you actually need evidence for.
- Revalidate and compare by identity, then keep the diff with the report.
Ruleset version 1.0.0, schema 1.0.0, verification date 11 November 2026.
Frequently asked questions
Is a product feed error a verdict on my whole catalog?
No. A feed error is a statement about one row and one field: a specific item, a specific attribute and a specific value in the file. Before changing anything, find which item, which field, and what the platform compares the value against — a shotgun repair destroys the ability to tell which change fixed the problem.
What is the difference between an error, a warning and Needs review?
An error means a required field is missing or malformed, an enum value is unsupported, a URL is not absolute, or an image is below the applicable minimum — deterministic verdicts. A warning means a recommendation was not followed or a future requirement is approaching, and doing nothing is legitimate. Needs review means the evidence cannot settle it, so a human must decide rather than receiving a coin flip dressed as a verdict.
Why will the checker not fix every issue automatically?
Because a GTIN, an MPN, a brand, a category, a price, a stock value or an image URL cannot be derived from the file. A generated identifier can collide with a real product and a price the merchant did not set is a commercial and legal problem, so the MVP offers only deterministic repairs and otherwise points at the exact field, rule and source to supply the real value from the source system.
How do I prove a repair actually worked?
Re-import the repaired file, re-run the same ruleset version, and compare issues by (rule, product, field) rather than by counting — then label each one Resolved, Persisting, New or Changed. A run with the same number of issues can still have fixed five and introduced five, and if the ruleset version changed the comparison has to be labelled cross-version.
What should I fix first?
Parse and structure first: fix the file format, duplicate headers and encoding before diagnosing any rule, because every downstream verdict depends on the rows being read correctly. Then identifiers and money, because those are cheap to verify and expensive to get wrong; then URLs, then images, then variants, then content; and only then opt in to remote checks, for the URLs you actually need evidence for.