The CSV import is the workhorse of Shopify catalogue management. It lets you create or update thousands of products at once, and it is also a famously unforgiving file format. A single missing comma, a mismatched header or an image link that returns an error can stop a row, a block of rows or the entire import. The error messages are short, and the cause is often a few lines away from where the message points.
This guide walks through the commonest Shopify CSV import errors in the order that most often finds the cause: structure, headers, handles, variants, images, encoding, inventory and metafields. It ends with a pre-flight checklist and a safe testing method. Shopify’s columns and limits change over time, so always compare with the current sample file and the Help Center before relying on any detail here. If you regularly load large catalogues, a repeatable path such as our bulk product upload service is often safer than hand-edited spreadsheets.
How the CSV is organised
A Shopify product CSV has one row per variant, and extra rows for additional images. The first row of a product holds its title, description and general fields. Following rows with the same handle add variants or images, and leave the product-level fields blank. The handle is the unique, URL-friendly identifier of the product, and it is how Shopify knows which rows belong together.
| Row type | Handle | Title and description | Option and variant fields | Image fields |
|---|---|---|---|---|
| First row of a product | Required | Required | First variant | First image, optional |
| Additional variant | Same as above | Blank | New option values, price, SKU | Optional |
| Additional image only | Same as above | Blank | Blank | Image source and position |
Error group 1: headers and template mismatch
The import maps columns by header name. If a header is spelled differently from the template, Shopify ignores the column or reports an invalid header. Shopify has revised its product template, for example when it introduced a standard product taxonomy, so a file created from an old template may not match.
- Symptom: a column is ignored, or a message says a header is invalid or missing.
- Cause: an old template, a renamed header, extra spaces or a changed case.
- Fix: download the current sample CSV from the import screen, copy your data into it and keep the header row untouched.
- Prevent: store the current template in your team’s shared folder and replace it when Shopify changes it.
Error group 2: handles
| Symptom | Cause | Fix |
|---|---|---|
| Variants appear as separate products | Handles differ slightly, for example a trailing space or different capitalisation | Make the handle identical on every row of a product, lower case, with hyphens |
| Rows skipped as duplicates | Two different products share a handle | Give each product a unique handle |
| Existing product duplicated instead of updated | The handle in the file differs from the live product’s handle | Export the live products and copy the handle exactly |
| Handle contains symbols or spaces | Copied from a title | Use lower-case letters, numbers and hyphens only |
Error group 3: variants and options
Variant problems are the most common source of confusing errors. Shopify products can have up to three options, such as size, colour and material, and every variant must have a unique combination of option values.
- Duplicate variant: two rows with the same option values. Fix by removing one or by adding a distinguishing option.
- Missing option value: one row has an option name but no value. Fill every option field for every variant row.
- Option names change between rows: the option name appears on the first row only in some templates; check the sample for where it belongs.
- Too many variants: Shopify has a limit on variants per product, so very large option sets may need splitting. Check the current limit in the documentation.
- Price missing or in the wrong format: use plain numbers without currency symbols or thousands separators, and use a full stop as the decimal mark.
Error group 4: images
Shopify does not upload images from your computer in a product import; it downloads them from the URLs in the file. If it cannot fetch a URL, the product may import without the image and an error is logged.
| Symptom | Likely cause | Fix |
|---|---|---|
| Image not imported | The URL needs a login or is blocked for downloads | Host images at a public address and test the link in a private browser window |
| Image not found | Typo, wrong extension or a moved file | Open every URL in the browser before importing |
| Wrong image order | Missing or duplicated image position values | Number positions from one, once per image |
| Image appears on the wrong variant | The variant image column does not match an image URL in the file | Use the exact same URL string in the variant image column |
| Very slow import | Large images or a slow host | Compress images and use a fast host or CDN |
Error group 5: encoding, quotes and line breaks
CSV is plain text, and plain text has traps. Spreadsheet programs can save in encodings that turn accented characters into garbage, or insert line breaks inside cells that split a row in two when the quoting is wrong.
- Save as CSV UTF-8, not a legacy encoding. In some spreadsheet tools, choose the UTF-8 option explicitly.
- Quote fields that contain commas, quotes or line breaks. Spreadsheet export usually does this correctly; hand-built files often do not.
- Escape double quotes inside a field by doubling them.
- Avoid smart quotes and special dashes in handles and option values.
- Check descriptions that contain HTML. Broken tags can cause strange formatting after import.
- Watch for leading zeros and long numbers. Barcodes and SKUs may be converted to scientific notation by a spreadsheet; format those columns as text.
Error group 6: inventory and locations
Inventory columns have changed as Shopify introduced multiple locations. In recent templates, quantities are set per location in columns named for the location, and they only apply if inventory is tracked for the variant. A mismatch between the location name in the file and the name in your admin means the quantity is ignored.
- Quantities ignored: the variant is not set to track inventory, or the location name does not match exactly.
- Negative or blank quantities: decide whether blank means zero or unchanged and follow the template’s rules.
- Updating stock via CSV: a set quantity replaces the current value, so it can overwrite sales made since you exported. For live stores, prefer an adjustment method; see inventory sync across sales channels for why.
Error group 7: metafields, categories and other fields
Newer templates support metafield columns and a standard product category. Metafield column headers follow a specific pattern that includes the namespace, key and type, and the metafield definition may need to exist first. A product category value must match one of Shopify’s allowed values. When these fields cause trouble, remove them, import the basics, then add the extra fields in a second pass. Decide first which facts belong in metafields, such as materials or care, and define them once.
How to read the error report
After an import, Shopify can show or email a report of rows that failed. Read it line by line, and note two numbers for each message: the row number and the field. Row numbers in the report usually refer to the data rows in your file, and a spreadsheet’s row numbers include the header, so allow for an offset of one. Fix a few errors, re-import only the failed rows and repeat until the report is clean. Do not re-import the entire file each time, because it may overwrite changes you have made in the admin in the meantime.
A pre-flight checklist
- Download the current sample CSV and confirm your headers match exactly.
- Check that every product has a unique, clean handle repeated on all its rows.
- Check that every variant has a unique combination of option values.
- Open a sample of image URLs in a private browser window.
- Confirm the file is saved as CSV UTF-8 and opens correctly.
- Format barcode and SKU columns as text so that numbers are not altered.
- Confirm prices are plain numbers.
- Confirm location names and inventory tracking settings if you set quantities.
- Back up the current catalogue by exporting it first.
- Import five to ten products as a test and inspect them in the admin.
A safe workflow for large imports
Large catalogues need a process, not just a careful file. Export the current catalogue first, so that you can restore if something goes wrong. Work on a copy of the file, never the original. Import a small slice that includes the awkward cases: a product with many variants, one with images, one with metafields. Review the result on the storefront and in the admin, including how it looks on a phone. Only then import the rest, in batches if the file is large. Afterwards, spot-check twenty products at random and compare them with the source.
| Stage | What to do | What you are checking |
|---|---|---|
| Back up | Export the current products | You can restore |
| Validate | Run the pre-flight checklist or a script | Structure and values |
| Test slice | Import 5 to 10 products | Variants, images, fields |
| Full import | Import in batches | Error reports per batch |
| Spot check | Review random products on the storefront | Real-world result |
If your imports are frequent or come from supplier feeds, the manual process becomes a risk in itself. A supplier feed sync validates and loads changes automatically, and our bulk product upload service builds a repeatable import with validation and a report. For the copy that goes into the file, see AI product descriptions that pass review.
Sources and further reading
Figures and rules in this guide come from the primary pages below. Platform limits and prices change, so open the page before you build on a number.
- Shopify Help Center: import and export products with CSV, template, columns and import behaviour
- Shopify Help Center: product variants, options and variant limits
- RFC 4180: common format for CSV files, how quoting and line breaks work in CSV