Why Shopify rejects a product CSV (and how to fix each cause)

When a Shopify product import fails, the message you get is often short. The file usually has one of a small number of problems. This guide goes through them in roughly the order they tend to cause trouble, and says how to fix each one.

You can find all of them at once by dropping the file into the free CSV Error Checker for Shopify. It runs in your browser, so the file isn't uploaded anywhere.

1. The file isn't UTF-8

Shopify's documentation asks for a CSV saved in UTF-8. Older versions of Excel, and many supplier systems, save CSV files as Windows-1252 (also called Latin-1). The file may import, but accented characters arrive garbled. "Café" becomes "Café", and an apostrophe becomes "’".

Fix: in Excel, use File → Save As → CSV UTF-8 (Comma delimited). If the text is already garbled ("Café"), the damage was done when someone opened and re-saved the file. CatalogPilot's repair tool can usually recover the original characters, and it shows each change.

2. Semicolons instead of commas

Excel in many European locales saves "CSV" files with semicolons, because the comma is the decimal separator there. Shopify expects commas.

Fix: change the list separator in your system's regional settings before saving, or convert the file. When the repair tool exports, it always uses commas.

3. The header row isn't the first row

Supplier price lists often start with a title line ("Wholesale price list – Autumn") above the real column headers. Shopify reads row 1 as the header.

Fix: delete the rows above the header. The checker finds the real header row and tells you where it is.

4. Column names Shopify doesn't recognise

Shopify only accepts its own column names. According to Shopify's help page, Collection is the only extra column you can add without breaking the format, apart from metafield, market and Google Shopping columns written in Shopify's own patterns. Columns like "RRP", "Item Code" or "Internal notes" need to be renamed or removed.

A related trap: Shopify has replaced the old singular Barcode column with a newer barcodes column, and a file that contains both fails to import.

Fix: rename supplier columns to Shopify's names, or use the column mapper to match them. Remove columns that have no Shopify equivalent.

5. Missing titles or handles

Every product needs a Title on its first row. The URL handle ties variant and image rows to their product. Shopify creates a handle from the title when the handle is blank, but extra rows without a handle can't be attached to anything.

Fix: make sure each product's first row has a title, and every row of a product carries the same handle. Handles may contain only letters, numbers and dashes, with no spaces.

6. Broken variant rows

Shopify's variant rules catch a lot of edited files:

• The first row of a product holds the product details. Later rows hold only the handle and variant details.
• Variant data such as SKU or weight needs Option1 name and Option1 value. If you leave them out, Shopify creates a default variant and deletes the existing variants of that product.
• A product can have at most three options.
• Two variants can't share the same combination of option values.

Fix: see the step-by-step guide to fixing Shopify CSV variant rows.

7. Values in the wrong format

Column	Shopify expects	Common mistake
Price, Compare-at price, Cost per item	Numbers only, e.g. 24.00	$24.00, 1,299.00, 24,00
Weight value (grams)	Whole grams, e.g. 180	0.18 kg, 1.5
Inventory quantity	Whole number	10 pcs, in stock
Published, Charge tax, Requires shipping	true or false	Yes, Y, 1
Status	active, draft or archived	Active, Published, blank

A blank Price doesn't cause an error. Shopify uses a default of 0.00, which is worse, because the product imports at a price of zero.

8. Images that can't be downloaded

Image links must be public https:// addresses, with one image per row. Shopify's documentation says file names shouldn't contain _thumb, _small or _medium. Links to shared Google Drive or Dropbox folders usually aren't direct image links.

9. Package dimensions half filled in

If you use the packed product length, width, height and unit columns, Shopify needs all four or none of them. A partial set causes an import error.

10. Blank cells overwriting good data

This one doesn't fail the import. It quietly removes data. With Overwrite products with matching handles turned on, a blank cell in a column that is present overwrites the existing value. Columns you leave out of the file aren't touched.

Fix: only include the columns you mean to change. CatalogPilot only writes the columns your original file contained, for this reason.

Before you import everything

Import a few products first and check them in your Shopify admin. No checker can guarantee that an import will succeed, because Shopify's importer has the final say. Fixing the problems above removes the documented causes of failure.