Shopify CSV Import Error: Common Causes and How to Fix Them
A Shopify CSV import error almost always points to a specific problem in your file: a header that doesn’t match Shopify’s template, a stray quote or blank line, a value in the wrong format, or an image link Shopify can’t reach. The error message usually names the problem and often the line number, so the fastest fix starts with reading it closely.
This guide groups the most common messages by type, explains what each one means and shows how to fix the file. Line numbers in Shopify’s messages refer to rows in your CSV, so open the file and go straight to that row.
Common Shopify CSV Import Errors and How to Fix Them
Find your error message in the groups below. Most files fail for one of a handful of reasons, and fixing the first error often reveals the next one, so expect to import more than once.
Header and file structure errors
These errors stop the import before any product is processed, because Shopify can’t read the file’s layout.
| Error message | What it means | How to fix it |
|---|---|---|
| Invalid CSV header: missing headers | The first row doesn’t match Shopify’s required headers | Copy the header row from Shopify’s template or a product export, and remove trailing spaces |
| A “Choose column headings” window appears | Some headers weren’t recognized | Pick the correct header for each column from the drop-down, or fix the headers in the file |
| Network error: Unexpected token < in JSON at position 0 | A column header doesn’t exactly match the template | Check spelling and capitalization, since headers are case-sensitive |
| Unquoted fields do not allow \r or \n | The file contains a blank line or a stray line break | Delete blank rows, including any between the header and the first product |
A missing-headers error can appear even when the header names look right. A different separator, such as semicolons instead of commas, or a hidden formatting issue from the program that saved the file can produce it. Merchants have fixed this by opening the file in Google Sheets and downloading it again as a CSV, which rewrites the file in a clean format.
Quote and character errors
These errors come from punctuation or encoding that confuses Shopify’s CSV reader.
| Error message | What it means | How to fix it |
|---|---|---|
| Illegal quoting on line X | An illegal character or a missing or stray quote on that line | Save the file as UTF-8 and check the quotes on the named line |
| Missing or stray quote on line X | Usually curly quotes from a spreadsheet program, or an extra quote mark | Replace curly quotes with straight ones and remove stray quotes |
| Garbled or unexpected characters after import | The file wasn’t saved as UTF-8 | Re-save the file as UTF-8, for example with Excel’s CSV UTF-8 option or through Google Sheets |
Curly quotes often arrive with text copied from documents or supplier sheets. A Find and Replace across the file, swapping curly quotes and apostrophes for straight ones, usually clears these errors in one pass.
Product and handle errors
These errors relate to how rows are grouped into products and to required product fields.
| Error message | What it means | How to fix it |
|---|---|---|
| Ignored line #-## because handle `example` already exists | Two different products in the file share a handle | Give each product its own unique handle |
| Ignored line #-## because it did not contain product data | A row has a handle but the product it starts has no title | Add the title on the product’s first row |
| Not a valid product category | The category doesn’t exactly match Shopify’s Standard Product Taxonomy | Use the exact category breadcrumb or category ID |
| Fulfillment service can’t be blank | The fulfillment service column is empty | Enter your service’s handle, or manual if you fulfill orders yourself |
Variant and inventory errors
Variant errors usually come from option columns, while inventory errors come from missing or invalid values.
| Error message | What it means | How to fix it |
|---|---|---|
| Validation failed: options are not unique | Two variants of a product have the same option values | Give each variant a unique combination of option values |
| Validation failed: price can’t be blank | A variant row has no price | Add a price to that row |
| Inventory policy is not included in the list | The out-of-stock policy has an invalid value | Use deny or continue |
| Inventory quantity can’t be blank, or is not a number | The quantity is missing or isn’t numeric | Enter a whole number, or leave the inventory tracker blank if you don’t track stock |
| Line is invalid (No details) | An existing option value was moved to a different option position | Import once with a temporary option name, then again with the final name |
| Daily variant creation limit reached, try again | The store hit the daily cap on new variants | Wait 24 hours, then import the next batch |
The variant creation limit only applies to large stores. Shopify’s help documentation describes it as applying to stores with 500,000 or more variants, outside Shopify Plus, which can create no more than 10,000 new variants by CSV or API in 24 hours. The timer starts with the first upload of the day.
Image errors
Image errors appear when Shopify can’t download or accept the image at the link in your file.
| Error message | What it means | How to fix it |
|---|---|---|
| Validation failed: getaddrinfo: nodename nor servname provided, or not known | The image URL is wrong or incomplete | Use a full, public, direct link to the image file |
| Validation failed: An error occurred while trying to download the image | The image file at that link is missing | Check the link in a browser and replace it if it doesn’t load |
| Validation failed: The uploaded image exceeds the 20 megapixel limit | The image is too large | Resize the image or use a smaller version |
| Incorrect header check | Shopify couldn’t process the image on that line | Remove the image from the line and retry; if that works, host the image elsewhere |
A good test for any image link is to open it in a private browser window. If the image loads on its own without a login or preview page, Shopify should be able to download it.
Metafield errors
Metafield errors usually mean a value doesn’t match what the metafield expects. “Validation failed: Value must be a valid product reference” appears when a metafield points to a product that doesn’t exist yet. Import the products first without that metafield value, then import again with the references added.
Metaobject references work the same way. A message such as “Value require that you select a metaobject” usually means the cell contains a display name instead of the metaobject entry’s handle, or the entry hasn’t been created yet.
When the Upload Fails or Never Finishes
Some import problems don’t come with an error message at all. If the upload times out or fails, the file may be too large, since Shopify’s product CSV can be up to 15 MB. Split it into smaller files and import them one at a time, keeping each product’s rows together.
If you see “Import job already in progress. Please wait until current one is finished,” a previous import is still processing. Give it time, and contact Shopify Support if it hasn’t finished after about an hour. Shopify also recommends using Google Chrome to avoid upload issues.
How to Avoid CSV Import Errors
Most errors can be prevented by starting from the right file. Download Shopify’s sample product CSV or export a few existing products, and build your import on that header row rather than typing headers yourself.
The program you edit in matters too. Merchants report imports failing after an export was edited and re-saved in Excel, then succeeding when the same edits were made in Google Sheets and downloaded as CSV. If you use Excel, save with CSV UTF-8 (Comma delimited) and avoid sorting the file, which can separate products from their variant and image rows.
Finally, test before importing the full file. Import two or three products that cover your harder cases, such as variants, several images and metafields, and fix any errors before uploading the rest. Bulkflow supports bulk import with field mapping for Shopify, so you can match your own spreadsheet columns to store fields instead of renaming every header to fit the template.
Conclusion
A Shopify CSV import error is frustrating, but the message almost always tells you where to look. Matching it to its cause, fixing that line and testing a small batch turns most failed imports into a quick correction. We hope this guide helps you resolve your Shopify CSV import error and get your products into your store. If spreadsheet imports are a regular part of your work, you can explore Bulkflow.
