Shopify CSV import errors: what each one means and how to fix it

Shopify checks a product CSV twice. When you upload it, it reads the header row and the quoting; if either is wrong, nothing imports. During the import, it validates each line, skips the ones that fail and lists them by line number in the confirmation email. A third group of mistakes passes both checks and changes your store in ways you did not intend.

The sections below follow that order. Error messages are quoted as Shopify writes them.

Finding the line Shopify means

Open the CSV in a text editor, not in Excel or Numbers, and go to the reported line. A spreadsheet can reformat SKUs, prices and dates when you save, which adds new errors while you fix one. Line numbers only match spreadsheet rows when no cell contains a line break; product descriptions often do. If the reported line looks fine, search for a handle near it instead of counting rows.

Shopify has also renamed columns over the years. Current exports use URL handle, SKU, Price and Product image URL, where older files used Handle, Variant SKU, Variant Price and Image Src. Both are still accepted. This guide uses the current names.

Invalid CSV header: missing headers

Shopify matches columns by their exact header text, including capitals. Product Name, sku or Qty from a supplier file are not recognised, and neither is SKU followed by a space you cannot see in a spreadsheet. The same problem can also appear as “Network error: Unexpected token in JSON at position 0”, or as a dialog asking you to choose column headings.

Export two or three products from your own store and paste that header row over yours. Shopify accepts one column beyond its own list, Collection. Any other extra column breaks the file.

Illegal quoting on line

A value that contains a comma is wrapped in straight double quotes. A curly quote pasted from a word processor, or a lone inch mark in a description, makes Shopify lose track of where a value ends. The related message is “Missing or stray quote on line”. A quote that belongs inside a value has to be doubled. The first line below fails, the second imports:

acme-glove,Acme Glove,"Fits 9" hands"
acme-glove,Acme Glove,"Fits 9"" hands"

If the reported line has no quotes at all, the cause is usually a character that is not UTF-8. Saving the file again as CSV UTF-8 clears it.

Garbled text after a successful import

There is no message for this one. The import works, and descriptions show ä where ä should be, or — in place of a dash. The file was saved in a regional encoding instead of UTF-8.

In Excel, use Save As and choose CSV UTF-8 (Comma delimited); the option called just CSV is not UTF-8. Google Sheets downloads are already UTF-8. Repairing the products afterwards takes another import, so open one imported description and check it before you import the rest.

Ignored line because handle already exists

Unless “Overwrite products with matching handles” is ticked, Shopify skips every row whose handle already exists in the store. If the row was meant to update that product, tick the option and import again.

If it was meant to be a new product, two products have ended up with one handle, usually because handles were generated from titles and two titles matched. Build handles from brand and supplier part number instead; those do not repeat.

Ignored line because it did not contain product data

Product fields such as title, description and vendor are read from the first row of each handle. Later rows only add variants and images. If the first row has no title, the product is never created. This usually happens after the file was filtered or sorted and a variant row moved to the top of its group. Put the title back on the first row and keep each product’s rows together.

Validation failed: options are not unique

Two variants of one product have the same option values, for example two acme-work-glove rows both marked Size M. Usually it is a copy-paste mistake in the value. Sometimes the same handle appears again further down the file, and Shopify treats both groups as one product.

A related message, “Line is invalid (No details)”, appears when a file moves an option value to a different option position. Shopify’s workaround is to import once with a temporary option name, then rename it.

Validation failed: price can’t be blank

The price must be a plain number with a dot as the decimal separator. “8,40 €” looks filled in but is not a number, so Shopify treats the cell as empty. 1.299,00 has to become 1299.00.

After converting a whole column, compare a few results with the supplier’s cost. A thousands separator that slipped through turns 1.299 into a price of 1.30.

Inventory quantity is not a number

Stock must be a whole number. “ten”, “5+”, “in stock” and 12.5 all fail; use 0 for out of stock. A tracked product with no quantity at all returns “Inventory quantity can’t be blank”. For products you do not track, leave the Inventory tracker column empty (Variant Inventory Tracker in older files) rather than the quantity.

Two related rules: the out-of-stock policy column accepts only deny or continue, and the quantity column only works for stores with one location. Stores with several locations update stock through Shopify’s separate inventory CSV.

An error occurred while trying to download the image

Shopify downloads every image from its link during the import. The link must be public and return the image file itself. Google Drive and Dropbox share links return a web page, so they fail. To test a link, open it in a private browser window: you should see the picture and nothing else.

“getaddrinfo: nodename nor servname provided” means the address itself is malformed, usually a typo or a missing https://. Images larger than 5000 × 5000 pixels fail with “exceeds the 20 megapixel limit”.

A broken file and its fix

Six of the problems above, in three product rows:

• Lines 2 and 3: the price is 8,40 € instead of 8.40.
• Line 3: the second glove variant is also Size M.
• Line 4: the hard hat’s first row has no title.
• Line 4: 1.2E+05 is Excel’s scientific notation; the real SKU is gone.
• Line 4: stock is the word ten.
• Line 4: the image link opens a Google Drive page.

The SKU had to be copied again from the supplier’s original file: once Excel has displayed 1.2E+05 and saved, the digits are lost. Title and Default Title is how Shopify’s own export marks a product without variants.

Less common messages

• Fulfillment service can’t be blank: enter manual unless you use a fulfillment app.
• Not a valid product category: the value must match Shopify’s product taxonomy exactly, as the full category path or its ID.
• Value must be a valid product reference: a metafield points to a product that does not exist yet. Import the products first, then import again with the metafields.
• Daily variant creation limit reached: stores with 500,000 or more variants can create up to 10,000 new variants a day by CSV. Import the rest the next day.
• An upload that times out with no message: a product CSV can be at most 15 MB. Split the file.

Mistakes that import without an error

None of these produce a message. Each one imports successfully and changes the store.

• With overwrite ticked, an empty cell clears that field in the store. A column left out of the file keeps its current value, so remove the columns you do not mean to change.
• An update that includes variant fields such as SKU but not Option1 name and Option1 value replaces the product’s variants with a single default variant.
• Renaming an option value, such as M to Medium, gives the variant a new ID. Apps, feeds and reviews linked to the old ID lose the connection.
• Excel turns long SKUs into 1.2E+05, removes leading zeros from barcodes and reads part numbers like 3-10 as dates. Format those columns as text before pasting data in.
• Sorting a finished CSV separates variant and image rows from their product. Shopify warns that images can be lost this way.
• An import cannot be cancelled once started, and there is no undo. Export your products first, so the export can be imported back.

Before you click Import

1. Header row copied from a current Shopify export, with no trailing spaces.
2. File saved as CSV UTF-8, with straight quotes only.
3. One handle per product, a title on its first row, its rows together.
4. Prices as plain numbers with a dot; stock as whole numbers.
5. SKUs and barcodes compared with the supplier file, not with what Excel displays.
6. A backup export taken, and ten products imported and checked before the full file.

When the supplier file keeps causing this

A supplier file that arrives with comma prices and spreadsheet-damaged SKUs this week will arrive the same way next week. Cleaning it by hand each time is where most of these errors come from.

Each fix above is a fixed rule, so it can be written once as a script: rename the headers, convert the prices, keep SKUs as text, group the variants, test the image links. The script runs on your own computer and stops with a list of problem lines instead of writing a file that Shopify will only half import.