P
Portaim

Shopify CSV Import Errors: Meanings, Fixes, and a Triage Checklist

Shopify CSV Import Troubleshooting Errors

If your Shopify product import fails, a practical starting point is: confirm the file format (UTF-8 + commas + correct headers), then use the exact error message to choose a fix. This guide sticks to Shopify’s documented messages and cautions, plus a few real-world patterns from Shopify Community threads.

10-step triage checklist (start here)

Use this checklist in order. Many “mystery” errors collapse into headers, delimiter, or UTF-8.

Step 1 — Backup/export first (before any upload)

  1. Export/backup your product data before you import. Shopify explicitly cautions to have a backup before starting an import.
  2. Keep an untouched copy of your working CSV/XLSX before you edit anything.

Step 2 — Confirm file basics (CSV, UTF-8, under 15 MB)

  1. Confirm you’re uploading a .csv file saved with UTF-8 encoding. Shopify says CSV files must use UTF-8, and a UTF-8 CSV is the file format used for import/export.
  2. Confirm the CSV file size is 15 MB or less. If you hit upload errors or timeouts, Shopify recommends splitting the CSV into smaller files and uploading each file.

Step 3 — Confirm delimiter is commas (not semicolons)

  1. Shopify’s CSV format is comma-separated: “Column headers must be separated by commas.”
  2. If your file uses semicolons (common in some regional Excel settings), Shopify may not recognize headers (community accepted fix: switch delimiter to commas).

Short snippet example (comma-separated header):

Handle,Title,Body (HTML),Vendor,Type,Tags,Published

Step 4 — Confirm headers match Shopify’s required template (case-sensitive, no trailing spaces)

  1. If you see “Invalid CSV header: missing headers”, Shopify says the first line should be:
Handle,Title,Body (HTML),Vendor,Type,Tags,Published,Option1 Name,Option1 Value,Option2 Name,Option2 Value,Option3 Name,Option3 Value,Variant SKU,Variant Grams,Variant Inventory Tracker,Variant Inventory Qty,Variant Inventory Policy,Variant Fulfillment Service,Variant Price,Variant Compare-at Price,Variant Requires Shipping,Variant Taxable,Variant Barcode,Image Src,Image Alt Text
  1. Shopify also says: check for extra white spaces at the end of the first line.
  2. If you get “Network error: Unexpected token < in JSON at position 0”, Shopify says your CSV column titles don’t match exactly and that column header names are case-sensitive (example: Handle not handle).

Step 5 — Fix quotes (straight quotes, no stray/curly quotes)

  1. If you see “Missing or stray quote on line …”, Shopify says Excel or another spreadsheet program can add curly (smart) quotes and those need to be replaced with straight quotes.
  2. Shopify’s suggested fix: open the file in a text editor, then search/replace curly quotes with straight quotes; also check for an extra stray quote on the error line.
  3. If you see “Illegal quoting on line …”, Shopify says it can be caused by illegal characters; ensure the file is UTF-8 encoded. Shopify also notes it can be caused by a missing or stray quote.

Tip from Shopify: “You can also use a program like Visual Studio Code or Sublime Text to edit and debug your CSV file.”

Step 6 — Run a small test import first

  1. Create a tiny CSV with a small number of products/variants first.
  2. Import that sample to confirm your formatting (headers, commas, UTF-8) before importing a full catalog.
  3. If you’re unsure about any field behavior beyond what’s in Shopify’s docs here, verify in Shopify Admin / Help Center before importing a large file.

Step 7 — Decide on overwrite vs ignore matching handles

  1. Shopify lets you choose “Overwrite products with matching handles.”
  2. Shopify warns: if you overwrite and a non-required column is blank in your import CSV, then the existing value in that column can be overwritten as blank.
  3. Shopify also explains: if a non-required column isn’t included in your import CSV, then the existing value remains the same.

Step 8 — Validate images (URLs + megapixel limits)

  1. If you see “Validation failed: An error occurred while trying to download the image”, Shopify says: “An image file is missing.”
  2. If you see “Validation failed: getaddrinfo: nodename nor servname provided, or not known”, Shopify says there’s a mistake in the image URL: it needs http:// in front and must be a publicly accessible direct link to the image.
  3. If you see “The uploaded image exceeds the 20 megapixel limit”, Shopify says images can be up to 5000 × 5000 px, or 25 megapixels, and you should reduce the size or use a different image.

Community pattern: even if an image URL opens in your browser, Shopify’s servers might not be able to access it. If you’re stuck, verify your image links are publicly accessible and direct (not behind authentication) and include http/https.

Step 9 — Validate variants/options (uniqueness + option position conflicts + daily limits)

  1. If you see “Validation failed: options are not unique”, Shopify says this is caused when a product has duplicate options (two variants with the same option values). Shopify also says: if option values are unique, the product could be duplicated elsewhere in the CSV with the same handle.
  2. If you see “Line is invalid (No details)”, Shopify says it can be caused by conflicts with existing product variant options when you attempt to change an option value from one option position to another. Shopify’s fix: use a temporary option name during the import, then update it afterward.
  3. If you see “Daily variant creation limit reached, try again”, Shopify says: for stores with 50,000 product variants (excluding Plus stores), no more than 1,000 new variants can be created by CSV uploads (or API) within a 24-hour timeframe, and the timer starts at the time of the first upload of the day.

Step 10 — Re-check price/inventory fields and policies

  1. If you see “Validation failed: price can’t be blank”, Shopify says: “The price needs to be added to this line.”
  2. If you see “Inventory quantity can’t be blank”, Shopify says the quantity needs to be set. If you’re not tracking inventory, leave Variant Inventory Tracker blank; otherwise the platform requires an inventory quantity.
  3. If you see “Inventory policy is not included in the list”, Shopify says the inventory policy needs to be set to deny or continue.

Step-by-step instructions (detailed workflow)

Follow this workflow for a safe, repeatable import process.

1) Export a backup + keep an untouched copy

  1. Export your product data and store a backup file. Shopify cautions to have a backup before import.
  2. Make a separate “working copy” you’ll edit, keeping the original untouched.
  1. If you can, use Google Sheets to work with your CSV files (Shopify recommends it).
  2. Ensure you save/export as CSV with UTF-8 encoding. Shopify emphasizes UTF-8 to prevent unexpected characters and warns that forgetting UTF-8 can corrupt data (and Shopify can’t recover corrupted files).
  3. Ensure:
    • Headers are comma-separated
    • Header names match Shopify’s template exactly (including case)
    • Tags list is wrapped in quotation marks (Shopify CSV formatting rule)

Short snippet example (Tags quoted):

Handle,Title,Tags
my-product,My Product,"tag1,tag2"

3) Upload in Shopify Admin (what to expect)

  1. Upload your CSV in Shopify Admin (verify the exact upload path in Shopify Admin / Help Center if you’re unsure).
  2. Shopify recommends using Google Chrome to avoid upload issues.
  3. When your CSV file is uploaded, Shopify says you receive a confirmation email at the email account used to set up your Shopify store.

4) If the import fails: use the exact error message to choose the fix

  1. Copy the exact error message.
  2. Match it in the “Error library by type” below.
  3. Apply the fix, then retry with a small batch first.

5) After import: review changes in the activity log

  1. Shopify states imports started with a CSV can’t be cancelled once they begin, and you can’t view a history of past imports.
  2. To review recent changes made by an import, Shopify says to check your store’s activity log.

Error library by type (message → meaning → fix)

All meanings and fixes below are based on Shopify’s documented text in the sources provided.

Header/format errors

Invalid CSV header: missing headers

  • What Shopify says: Your first line should match Shopify’s header template, and you should check for extra white spaces at the end of the first line.
  • Fix:
    1. Replace your header row with Shopify’s template header line (see checklist Step 4).
    2. Remove trailing spaces at the end of the header row.
    3. Confirm delimiter is commas (not semicolons).

Choose column headings window appeared

  • What Shopify says: This window displays when the headers of your CSV file are incorrect.
  • Fix:
    1. Fix the header row to match Shopify’s required template exactly (including case).
    2. Re-upload.

Network error: Unexpected token < in JSON at position 0

  • What Shopify says: Column titles don’t match exactly; header names are case-sensitive.
  • Fix:
    1. Compare headers to Shopify’s sample/template and match exactly (e.g., Handle not handle).
    2. Re-upload.

Encoding/quoting errors

Illegal quoting on line …

  • What Shopify says: Caused by an illegal character in the CSV. Ensure the file is UTF-8 encoded. Sometimes caused by a missing or stray quote. Shopify also notes illegal quoting can occur when there are non-UTF-8 encoded commas and quotation marks.
  • Fix:
    1. Re-save/export as UTF-8.
    2. Inspect the line in a text editor for misplaced commas/quotes and fix them.
    3. Re-upload.

Missing or stray quote on line …

  • What Shopify says: Can be from curly (smart) quotes added by Excel or another spreadsheet program; replace with straight quotes. Another cause is an extra stray quote. Shopify suggests using a text editor and search/replace.
  • Fix:
    1. Open the CSV in a text editor (VS Code is fine).
    2. Search/replace curly quotes with straight quotes.
    3. Find the error line and remove any stray quote.
    4. Re-save as UTF-8 and re-upload.

Variant/option errors

Validation failed: options are not unique

  • What Shopify says: Duplicate options (variants with the same option values). If option values are unique, the product might be duplicated elsewhere in the CSV with the same handle.
  • Fix:
    1. Check for duplicate option value combinations within the same product.
    2. Search the CSV for the same handle duplicated with the same option values.

Line is invalid (No details)

  • What Shopify says: Can be caused by conflicts when changing an option value from one option position to another; the import fails when an existing option value is assigned to a new option position. Shopify’s fix: use a temporary option name during the import, then update afterward.
  • Fix:
    1. Use a temporary option name during import to avoid the option-position conflict.
    2. After the import, update the option name afterward (verify exact steps in Shopify Admin / Help Center).

Daily variant creation limit reached, try again

  • What Shopify says: For stores with 50,000 product variants (excluding Plus stores), no more than 1,000 new variants can be created via CSV uploads (or API) within 24 hours; timer starts at the time of the first upload of the day.
  • Fix:
    1. Reduce the number of new variants created in a 24-hour period.
    2. Try again after the 24-hour window (counted from the first upload time of that day).

Image errors

Validation failed: An error occurred while trying to download the image

  • What Shopify says: “An image file is missing.”
  • Fix:
    1. Verify the Image Src value points to an image that Shopify can retrieve (public access).
    2. If needed, remove image rows and re-test with a small batch, then add images back after confirming URLs.

Validation failed: getaddrinfo: nodename nor servname provided, or not known

  • What Shopify says: There’s a mistake in the image URL; it needs http:// in front, and must be a publicly accessible direct link to the image.
  • Fix:
    1. Ensure image URLs start with http:// or https://.
    2. Ensure the URL is a publicly accessible direct link to the image.

Validation failed: The uploaded image exceeds the 20 megapixel limit

  • What Shopify says: Images can be up to 5000 × 5000 px, or 25 megapixels; reduce the size or use a different image.
  • Fix:
    1. Resize or replace the image to comply with Shopify’s limits.
    2. If you see other image-related errors not listed here, verify in Shopify Admin / Help Center.

Price/inventory errors

Validation failed: price can’t be blank

  • What Shopify says: The price needs to be added to the line.
  • Fix:
    1. Add Variant Price for that line.

Inventory quantity can’t be blank

  • What Shopify says: Quantity needs to be set; if not tracking inventory, leave Variant Inventory Tracker blank; otherwise quantity is required.
  • Fix:
    1. If tracking inventory: set Variant Inventory Qty to a value.
    2. If not tracking inventory: leave Variant Inventory Tracker blank (and verify your setup in Shopify Admin / Help Center).

Inventory policy is not included in the list

  • What Shopify says: Must be deny or continue.
  • Fix:
    1. Set Variant Inventory Policy to deny or continue.

Product data errors

Ignored line #-## because handle example already exists

  • What Shopify says: Handle uniquely identifies each product; make sure each product has a unique handle in the CSV.
  • Fix:
    1. Ensure handles are unique for each product you intend to create as new.

Ignored line #-## because it did not contain product data

  • What Shopify says: At least one product has a handle, but no product title.
  • Fix:
    1. Ensure rows with a handle also include a product title.

Fulfillment service can’t be blank

  • What Shopify says: Enter the name of the fulfillment service; if not using one, set it to manual.
  • Fix:
    1. Set Variant Fulfillment Service to your service name or manual if not using a fulfillment service.

Common pitfalls (what causes repeat failures)

These patterns show up repeatedly in Shopify’s docs and community troubleshooting.

1) Excel/Numbers edits that introduce format issues

  • Shopify cautions that importing a CSV that has been sorted in Excel or Apple Numbers can remove products from relevant image links and cause images to be lost.
  • Community examples show Excel workflows can trigger illegal quoting and missing headers problems after “Save As CSV.”

2) Wrong delimiter (semicolon instead of commas)

  • Shopify requires comma-separated headers.
  • A Shopify Community accepted solution for “Missing headers: Title” was that the file was delimited by semicolon; switching to commas resolved it.

3) Header mismatches (case sensitivity + trailing spaces)

  • Shopify says header names are case-sensitive and must match the required template exactly.
  • Shopify also warns to check for extra white spaces at the end of the first header line.

4) UTF-8 not confirmed → unexpected characters or corruption risk

  • Shopify requires UTF-8 and notes that incorrect encoding can cause unexpected characters.
  • Shopify warns that forgetting to confirm UTF-8 can corrupt your data when re-uploaded, and Shopify can’t recover corrupted files.

5) Overwrite surprises when columns are blank or dependent

  • Shopify warns: when overwriting matching handles, blank non-required fields can overwrite existing values as blank.
  • Shopify warns: including certain columns without related option columns can cause deletions/removals (example: SKU included without Option1 name/value can delete variant options).

Safety notes (do this every time)

Shopify’s cautions are worth treating as a standard operating procedure.

  1. Backup/export first. Shopify explicitly cautions to have a backup of product data before import.
  2. Test a small batch first. Start with a minimal CSV to validate headers, delimiter, and UTF-8 before importing a full catalog.
  3. Imports can’t be cancelled. Shopify says product imports started with a CSV can’t be cancelled once they begin, and you can’t view a history of past imports.
  4. Use overwrite carefully. Shopify explains how “Overwrite products with matching handles” works, including:
    • blank non-required fields can overwrite existing values as blank
    • excluding a non-required column can keep existing values
    • including a dependent column without related columns can delete/remove existing data (Shopify’s SKU/Option example)
  5. Be careful when changing option values. Shopify warns that changing Option values can delete existing variant IDs and create new ones, and this can break third-party dependencies on variant IDs.

FAQ

1. What does “Invalid CSV header: missing headers” mean?

Shopify says your first CSV line should match its required header template, and you should check for extra white spaces at the end of the first line.

2. Why do I see the “Choose column headings” window?

Shopify says it appears when the headers of your CSV file are incorrect.

3. How do I fix “Network error: Unexpected token < in JSON at position 0”?

Shopify says it happens when column titles don’t match the required headers exactly, and header names are case-sensitive. Compare your headers to the sample/template and match exactly (e.g., Handle not handle).

4. How do I fix “Illegal quoting on line …”?

Shopify says ensure the CSV is UTF-8 encoded; it can also be caused by missing/stray quotes or non-UTF-8 commas/quotation marks. Re-save as UTF-8 and inspect the problematic line in a text editor.

5. How do I fix “Missing or stray quote on line …”?

Shopify says curly (smart) quotes from Excel can cause it; replace with straight quotes using a text editor, and remove any stray extra quote on that line.

6. Why do I get “Validation failed: options are not unique”?

Shopify says it’s caused by duplicate options (variants with the same option values). If option values are unique, Shopify says the product could be duplicated elsewhere in the CSV with the same handle.

7. What does “Line is invalid (No details)” mean?

Shopify says it can be caused by conflicts when trying to change an option value from one option position to another. Shopify’s fix is to use a temporary option name during import, then update afterward.

8. Why are my images failing with “getaddrinfo…”?

Shopify says the image URL needs http:// in front and must be a publicly accessible direct link to the image. Community reports also note Shopify’s servers might not access some URLs even if they open in a browser.

9. What does “The uploaded image exceeds the 20 megapixel limit” mean?

Shopify says images can be up to 5000 × 5000 px, or 25 megapixels; reduce image size or use a different image.

10. What does “Src cannot be blank” mean?

This specific meaning isn’t defined in the Evidence Pack. If you see it, verify in Shopify Admin / Help Center and check whether any required image-related fields are empty in the rows that reference images.