Shopify product CSV import errors: common causes and fixes
A Shopify product CSV import can fail loudly—with row errors—or quietly, with the admin looking fine while your catalog does not match the file you uploaded. This guide maps the usual failure modes merchants hit in forums and support threads, points to Shopify’s own troubleshooting material, and gives you a fast order of operations before you waste hours re-editing data.
Shopify documents CSV structure and known pitfalls in Using CSV files to import and export products and Solutions to common product CSV import problems. When in doubt, trust the official column list from a fresh export over a third-party template.
Start here: three questions
Before touching individual fields, answer these:
- Was the file saved as UTF-8? Wrong encoding breaks quotes and special characters; Shopify’s importer is strict about CSV text integrity.
- Do headers match Shopify’s export exactly? Extra spaces, renamed columns, or out-of-order custom columns cause rows to drop fields or map them to the wrong properties.
- Do handles and variants follow one row per variant? The
Handleties variant rows to a product; option columns must line up or you get split products, missing variants, or “Default Title” oddities.
Symptom: importer errors with “illegal quoting” or garbled text
These usually trace back to file encoding, delimiters edited by a spreadsheet app, or unescaped quotes inside fields. Re-save as UTF-8 from a text editor you trust, or avoid round-tripping through Excel for the final file. The dedicated walkthrough is in Shopify CSV UTF-8 and quoting.
Symptom: columns not recognized or values land in wrong places
Compare your first row to a CSV exported from your own store (same Shopify plan and features). Even minor header drift—spaces after the name, renamed metafield columns, or an older template downloaded from a blog—can make Shopify ignore data you think you imported. See column headers not recognized.
Symptom: duplicate products, merged wrong, or missing variants
The Handle is the join key. Reusing a handle attaches new rows to an existing product; typos create duplicate products. Option name/value pairs must be consistent row to row. Read handles and variants and variant options and Default Title.
Symptom: import “succeeds” but nothing looks right
Check the import summary email Shopify sends, re-export products, and compare a single handle in your file against what landed in admin. Inventory and image fields are frequent culprits when a column was silently skipped. Silent failure troubleshooting walks through that detective work.
Symptom: numbers, SKUs, or dates changed after editing
That pattern usually means the CSV passed through Excel or Sheets in a way that auto-formatted cells. The fix is to stop using spreadsheet software for the final export, or to use import workflows that never let the app reinterpret data types. See Excel corruption.
Workflow choices for large catalogs
For big catalogs, the import-export loop from Shopify (export → edit → re-import) is still the safest way to preserve columns your plan exposes. Building a file from scratch is fine if you generate headers programmatically or use a tool that targets Shopify’s schema. Bulk update workflow compares the two approaches; building CSV without a spreadsheet covers tooling trade-offs honestly.
FAQ
Should I start from Shopify’s sample CSV or from an export?
Prefer an export from your store when possible. It includes the exact headers your shop supports today, including fields that vary by plan or activated features.
Why do forum fixes contradict each other?
Shopify’s CSV surface has changed over time, and Metafields and markets add headers that did not exist in older tutorials. Anchor every file to current admin behavior, not a screenshot from an old thread.
When is native CSV the wrong tool?
Very large catalogs, frequent incremental syncs, or complex enrichment pipelines often move to bulk edit apps or the Admin API. CSV remains the lowest-friction path for one-off migrations and straightforward variant grids—until friction proves otherwise.