Shopify's product CSV is powerful because it lets you update hundreds of products at once, but the format is unforgiving. One misplaced comma or a single missing Handle can abort an entire import and leave you staring at a vague error log. This guide walks through the failures we see most often in real stores and how to fix each one without rebuilding the file from scratch.
Why Shopify's format is easy to break
Unlike a simple product list, a Shopify export is a relational structure flattened into rows. A product with three sizes and two colors becomes six rows linked by the Handle column. The first row carries the Title, Body, Vendor and Tags; the following rows leave those cells empty and repeat only the Handle and the variant fields. If any row breaks that contract, the link between product and variants snaps.
Understanding that contract is the key to every fix below.
Error 1: "Column headers are invalid" or "Missing required header"
What you see: Shopify rejects the file before it even starts, listing a header name.
Why it happens: Header names are case-sensitive and must match Shopify's expected names exactly — including spaces and parentheses. Variant Price is not the same as Variant price or Price. A common culprit is opening the export in Excel, adding a column, and re-saving; Excel may trim or re-capitalize headers, or save with a different encoding that adds a BOM character to the first header.
How to fix: Download a fresh export from Shopify and compare its header row to yours cell by cell. Do not retype headers. Copy the exact header row from a working export and paste your data beneath it. Save as CSV UTF-8 (Comma delimited) and verify the file opens as UTF-8 without a leading invisible character.
Error 2: "Handle has already been taken" or products merging incorrectly
What you see: You intended to create a new product, but it overwrites an existing one, or two products collapse into one.
Why it happens: The Handle is the product's identity. If you reuse a Handle that already exists in your store, Shopify treats every row with that Handle as part of the existing product. If you leave Handle blank on a variant row, Shopify cannot link it to its parent.
How to fix: For new products, generate a Handle that does not exist yet — typically a URL-friendly version of the title in lowercase with hyphens. For existing products, keep the Handle exactly as exported. Never leave Handle blank on any row that belongs to a product. If you need to change a Handle, do it as a separate step after the import succeeds.
Error 3: Variant prices, SKUs or inventory landing in the wrong product
What you see: Prices appear on the wrong variant, or inventory updates affect a different size than intended.
Why it happens: Variant rows are ordered. Shopify expects all rows for one product to be contiguous, grouped by Handle, with the parent row first. If you sort the file by price or filter and re-sort, variant rows can become interleaved with another product's rows. The parser then attaches them to the wrong Handle.
How to fix: Before editing, sort by Handle (A→Z) and keep that order. Do bulk price changes by filtering in place, not by re-sorting. If you use find-and-replace, scope it to the Variant Price column only — replacing "19.99" globally will also hit descriptions that contain the same number. A structured editor like CSV Pilot applies changes by product, not by text search, which avoids this class of error.
Error 4: Images not importing or duplicating
What you see: Images are missing, or the same image appears five times, or the import is much slower than expected.
Why it happens: Shopify's image model is row-per-image. A product with five photos needs five rows that repeat the variant data and differ only in Image Src. If you put all five URLs in one cell separated by commas, Shopify reads it as a single malformed URL. If you add an image URL to every variant row, that image gets duplicated across variants.
How to fix: Follow the one-image-per-row pattern. For a product with three variants and two images, the cleanest pattern is variant rows first, then one row per additional image with only Handle and Image Src filled. Test image URLs in a browser before importing — a 404 image URL will not fail the import, but it will leave the product imageless.
Error 5: "Inventory will not be overridden" or stock not updating
What you see: Inventory quantities stay at the old value despite the CSV containing new numbers.
Why it happens: Shopify's inventory import respects the location and the "Inventory will not be overridden" logic when Variant Inventory Qty is blank or when the product tracks inventory at a different location. An empty inventory cell does not mean zero — it means "do not change."
How to fix: Fill every Variant Inventory Qty you intend to change with an explicit number, including zero if you want to zero out stock. If you use multiple locations, ensure the CSV's location columns match the location where you track that variant.
A safe workflow for any bulk edit
- Export a fresh file from Shopify and keep the original untouched.
- Make changes in a copy and keep the header row exactly as exported.
- Validate before importing — check that every row has the same number of columns as the header, that handles are consistent, and that image URLs resolve.
- Test with 5 products — import a small slice, verify the result in the admin, then run the full file.
- Keep the original until the new data is confirmed.
When the file is large or the edit is rule-based ("increase all Variant Prices by 10% where Vendor is Acme"), a chat-driven tool saves hours. Upload the export to CSV Pilot, describe the change in plain language, and let the agent apply it product by product with exact numeric handling. You review the preview grid before exporting, which catches the shifted-column and handle errors above before they reach Shopify.