Why does my Shopify CSV import keep failing?

Start here: the three-minute check

Before you hunt for one error, run these checks. They clear most failed imports.

1. Headers. Open Shopify's sample product CSV and compare your first line to it, letter by letter. Header names are case sensitive. Look for a stray space at the end of the first line.
2. Encoding. Save the file as UTF-8, a text format that handles accents and symbols. Google Sheets does this by default. Other spreadsheet programs, such as Excel (Microsoft's spreadsheet program), may need an extra step when you save, so check their save options.
3. File size. A product CSV cannot exceed 15 MB. If the upload errors or times out, Shopify says to split the file and upload each part.
4. Sorting. If you sorted the file in a spreadsheet program, variants and images may have come apart. Shopify warns that this can cut products off from their image links, so the images are lost.
5. Test. Cut the file to ten rows and import those. If ten rows work, the problem is in a row you removed.

One more thing before you retry: Shopify says an import cannot be canceled once it starts, and there is no import history. If a failed import partly ran, check your store's activity log to see what changed.

The error messages, causes and fixes

These are the messages listed on Shopify's help pages, with the fix for each.

Message	Cause	Fix
Network error: Unexpected token < in JSON at position 0	Your headers do not match the template	Compare to the sample. Use Handle, not handle. Fix case and spelling.
Invalid CSV header: missing headers	A required header is missing, or the first line has extra spaces	Match the sample header row exactly. Remove trailing spaces.
Choose column headings window appears	Your headers are not recognized	Pick the right heading from each dropdown, or fix the headers in the file.
Illegal quoting on line / Missing or stray quote	Curly (smart) quotes, a stray quote, or non-UTF-8 text	Save as UTF-8. In a plain text editor, replace curly quotes with straight quotes and remove stray ones.
Line is invalid (No details)	You moved an existing option value to a different option slot	Rename the option temporarily, import, then import again with the real name (see below).
Ignored line because handle already exists	Duplicate handle, or the product exists and the overwrite box is off	Make handles unique, or tick the overwrite box on purpose.
Ignored line because it did not contain product data	A handle with no product title	Add the Title on the first row of the product.
Validation failed: options are not unique	Two variants share the same option values, or a product repeats elsewhere with the same handle	Make each variant's combination unique. Search the handle for a duplicate.
Validation failed: price can't be blank	A variant row has no price	Add the price as a plain number.
Inventory quantity can't be blank / is not a number	Stock tracking is on but the quantity is missing or has text in it	Enter a number, or leave the Inventory tracker column blank if you do not track stock.
Inventory policy is not included in the list	Continue selling column holds something other than deny or continue	Use only deny or continue.
Fulfillment service can't be blank	Empty fulfillment column	Enter manual if you use no fulfillment service.
Not a valid product category	Category text does not match Shopify's list	Use the full category breadcrumb or the category ID exactly as Shopify's taxonomy shows it.
Daily variant creation limit reached	Stores with 500,000 or more variants (not on Shopify Plus, its top-tier plan) can create 10,000 new variants per 24 hours by CSV or API (the way programs talk to Shopify directly)	Wait for the 24 hour timer, which starts at the first upload of the day, and split the work across days.
Validation failed: Value must be a valid product reference	A metafield (an extra custom field on a product) points to a product that is not in the store yet	Import the products first without that metafield, then import again with it.

Image errors

A CSV holds image links, not pictures, so many failures are about links. These are the image messages Shopify lists.

• "An error occurred while trying to download the image." The image file is missing at that address.
• "getaddrinfo: nodename nor servname provided, or not known." The link is wrong. It needs http:// or https:// in front and has to be a direct, public link to the image file, not to a web page.
• "Incorrect header check." Shopify's tip is to remove the image from that row and retry. If that works, host the image somewhere else.
• "The uploaded image exceeds the 20 megapixel limit." Shopify says product images can be any size up to 5000 x 5000 pixels. Shrink the picture.

Also watch for this one: if you removed products or images from your store after an export and then import the old file, it fails because the old links are dead. And Shopify warns that external image links must be publicly accessible. A link that opens for you only because you are logged in to a drive or a supplier portal will not open for Shopify.

Variant and handle problems

Variants cause the most confusing failures. Shopify's rules are simple, but supplier files break them constantly.

• A product with variants needs the same handle on every row. The first row carries Title, Description, Vendor and Tags. The following rows leave those four empty.
• A handle can contain letters, dashes and numbers but no spaces.
• If a row has a SKU or a weight, Option1 name and Option1 value must be filled in as well. If you update variant data and leave those two columns out, Shopify deletes the variant options.
• A product can have at most 3 options.
• A file with both the old Barcode column and the new Barcodes column fails to import.
• The four packed product size columns must all be filled or all be empty.

Fixing "Line is invalid (No details)"

This happens when you try to move an option value between slots. Say Size was Option 1 and you now want Type in Option 1 and Size in Option 2. Shopify checks for duplicate names before it writes anything, so the move fails. The fix from Shopify: rename Size to something like "Size." (with a period) for the first import. Then import a second file that changes the name back. Two imports, but both succeed.

When it imports but the result is wrong

• Strange symbols in descriptions. The file was not UTF-8. Re-save it as UTF-8 and import again with the overwrite box ticked, or fix the few affected products by hand.
• Vendors, types or tags are blank. You ticked the overwrite box and the file had empty cells in those columns. Blank cells in columns that are in your file erase stored values. Restore from your backup export.
• Apps broke after the import. Changing option values deletes old variant IDs and creates new ones. Apps that stored the old IDs lose track of the variant.
• Products imported as hidden. Check the Status column, which accepts active, draft or archived, and the Published on online store column.
• Images lost. The file was probably sorted in a spreadsheet editor.

Why the import seems slow

Shopify downloads every image from its link during the import, so a file with hundreds of image links can take a while, and a slow image host makes it worse. Shopify's advice for uploads that time out is to split the file into smaller ones. I would aim for a few hundred products per file. Check your email: Shopify sends a message after you upload, and failed rows in an inventory import are reported by email too.

When repeated import errors mean a bigger problem

One failed import is a typo. The same failure every week is a process problem. The usual root cause is a supplier or warehouse file that was never designed for Shopify, so every new copy needs hands-on cleaning. If you are spending hours reshaping the same kind of file, there are two fixes:

• Have a script or an AI tool reshape the file to the Shopify format for you, then check a sample. My guide to fixing Shopify import errors with AI gives the exact prompt, and my overview of AI document processing explains the idea behind turning messy files into clean data.
• Replace the file with an automatic feed from the supplier into Shopify. My Shopify CSV import guide covers when that switch makes sense.

If your stock numbers are also off, the issue may be that no one system owns them. The inventory management system guide covers that.

How I'd approach this

I would never debug a big file. I would cut it to ten rows, fix those, and then add rows back in batches of fifty. When a batch fails, the bad row is in that batch. I would keep one known-good file as my template and build every new file by pasting data under its header row. And I would keep an export of the store before any overwrite import. Those three habits take failed imports from a lost afternoon to a five-minute fix. If you are fighting the same supplier file every week, treat it as a process to fix once, not a chore to repeat.