Overview
Shopify's native CSV import is powerful, but its error messages can be cryptic and frustrating. This FAQ-style troubleshooting guide walks you through the 10 most common Shopify CSV import errors, from UTF-8 encoding failures and broken image URLs to variant duplication and metafield reference issues. Each answer is self-contained with a clear fix, so you can jump straight to whatever is blocking your import right now. Whether you are migrating from another platform or doing a bulk catalog update, these solutions will save you hours of guesswork.
Contents
File-Level Errors: Encoding, Headers, and File Size
How do I fix UTF-8 encoding errors in my Shopify CSV?
If you see garbled characters, strange symbols, or accented text rendering incorrectly after import, your CSV file almost certainly is not saved with UTF-8 encoding. Your CSV file must be UTF-8 encoded. Shopify requires CSV files to use UTF-8 encoding. Files saved in Latin-1, Windows-1252, or other legacy encodings will produce garbled characters or fail to parse special characters in product titles or descriptions.
To fix this, open the file in a text editor and save it again, making sure that you specify UTF-8 encoding. Google Sheets always exports CSVs as UTF-8 automatically, so no action needed there. In Excel, choose "CSV UTF-8 (Comma delimited)" from the Save As file type dropdown. If you are on an older version of Excel that does not offer that option, open the file in Google Sheets and export from there instead.
What causes "Illegal quoting on line" errors?
This error is caused when there is an illegal character in the CSV file that you are trying to import. Sometimes, this error is caused by a missing or stray quote. The most frequent culprit is curly (smart) quotes. Excel and Google Sheets often convert straight quotes (") into curly quotes. Shopify's parser does not recognize curly quotes as field delimiters, so fields appear broken.
To resolve this, this can be the result of Excel or another spreadsheet program adding curly quotes (smart quotes). These need to be replaced with straight quotes. Open the file using a text editor, and do a search and replace to change curly quotes into straight quotes. Also make sure any field containing commas is wrapped in double quotes, and any double quote inside a field value is escaped by doubling it ("").
Why does Shopify say my CSV headers are incorrect?
This window displays when the headers of your CSV file are incorrect. Shopify expects exact column names like Handle, Title, Body (HTML), Variant Price, and so on. Shopify expects exact column headers. If you rename or slightly modify these headers, Shopify won't recognize them.
The fix: download Shopify's sample product CSV or export an existing product from your store to get a working template with correct headers. Remember to check for extra white spaces at the end of the first line. Even a single trailing space after the last header can cause the import to fail.
My CSV file is too large to upload. What do I do?
When importing content using a .csv file, there's a file size limit of 15MB per file for products, inventory, and customer data. If your catalog exceeds this, split the CSV file into multiple smaller files, and then upload each file.
For large catalogs, split your file into batches of a few hundred rows. This makes it much easier to isolate and fix problems when something goes wrong. Third-party apps like Matrixify can handle file sizes up to 20 GB, making them a better fit for very large catalogs.
Variant and Product Data Errors
Why am I getting "Options are not unique" errors?
This error happens when a product has duplicate options. Check if two variants of the same product have identical option values (e.g., two medium black shirts). Edit the option values to ensure they are unique, or remove the duplicate product.
This often sneaks in when you copy and paste variant rows and forget to update the option values. Open your CSV in a spreadsheet, sort by Handle, and visually scan each product's variant rows to confirm every combination of Option1 Value, Option2 Value, and Option3 Value is unique within that product.
Why did my variant IDs change after CSV import?
This is one of the most disruptive surprises in Shopify CSV imports. Changing data in the Option1 value, Option2 value, or Option3 value columns of the product CSV file deletes existing variant IDs, and creates new variant IDs. This means any external systems, apps, or discount rules pointing to those old variant IDs will break.
If you only need to update prices, inventory, or descriptions, avoid touching the option value columns entirely. For complex updates that require changing option values, use the Shopify GraphQL Admin API or an app like Matrixify, which can update products while preserving their IDs.
What does "Daily variant creation limit reached" mean?
Shopify limits non-Plus stores to creating no more than 1,000 new variants via CSV uploads within 24 hours. As of late 2025, Shopify increased the per-product variant limit from 100 to 2,048. This is a significant expansion for stores selling highly configurable products, but it also means CSV files can now contain far more variant rows per product, making structural consistency even more critical.
Wait for 24 hours after the first upload of the day to try again. If you often hit this limit, consider splitting your CSV file into smaller uploads spread across several days. Shopify Plus stores are not subject to this daily throttle.
Why does my metafield reference fail during import?
This error happens when your CSV tries to reference a product in a metafield, but the product doesn't exist in your store yet. Because product references in metafields must reference an existing product, you can fix this by adding the product to your store before you reference it in a metafield.
The recommended approach is a two-stage import. First, import your products to your store without metafield values. Next, add the metafield values back to your CSV file, and then perform another import that overwrites the products. This updates all your products to have the required metafield values, and ensures that the products exist in your store before referencing them in metafields.
Side note - Shopify CSV import supports product-level metafields but not variant-level metafields. Variant metafield values included in your CSV will be silently ignored. Use the Shopify bulk editor or the GraphQL Admin API to manage variant metafields.
Image Import Errors
Why are my product images missing after CSV import?
Image failures are especially sneaky because a Shopify CSV import can complete with a "success" status while every image fails to attach. The import process does not block on image errors; it logs them and moves on. This makes image issues particularly insidious because they often go unnoticed until a customer sees a listing with no photos.
Common causes include: non-public URLs (like Google Drive or Dropbox share links), you need to upload images to any server where the direct link can be placed for that image. It should not be any file hosting service like Google Drive, Dropbox or other because it doesn't provide the direct link to the image file. Also make sure every URL in the Image Src column starts with https:// and returns an actual image file when opened in a browser.
Tip - Importing a CSV file that has been sorted by a spreadsheet editor such as Microsoft Excel or Apple Numbers might cause your products to be removed from their relevant image links on the CSV, and your product's images will be lost. Never sort an exported Shopify CSV in a spreadsheet before re-importing.
How do I fix "Image exceeds 20 megapixel limit" errors?
Shopify enforces a 20-megapixel limit per image (roughly 5000 x 5000 pixels). Images exceeding this will be rejected. Stick to JPEG, PNG, GIF, or WebP. Less common formats may not be processed.
Resize your images before uploading. Batch tools like ImageMagick, Squoosh, or Photoshop's image processor action can handle this quickly across hundreds of files. After resizing, update the Image Src URLs in your CSV to point to the new files, then re-import.
Pre-Import Checklist and Alternatives
What should I check before every Shopify CSV import?
Run through this checklist before every upload to catch most errors before they reach Shopify:
Encoding: Confirm the file is saved as UTF-8. Use Google Sheets if unsure.
Headers: Always start with the official CSV template to reduce formatting mistakes.
Handles: Verify every product has a unique handle and that variant rows share the same handle as their parent product.
Required fields: The only mandatory column for new products is the "Title." However, if your products have variants, you'll also need to include the "Handle" column.
Images: Test a sample of Image Src URLs in your browser to confirm they are publicly accessible and return an image.
Inventory policy: The inventory policy needs to be set to 'deny' or 'continue'.
Test first: Import 2 to 5 products first to isolate errors.
Tip - There is also no undo. Once a Shopify CSV import runs, you cannot cancel or roll it back. Mistakes require manual fixes, product by product. Always back up your current product data by exporting before running a new import.
When should I use Matrixify instead of native CSV import?
Shopify's built-in CSV import works well for simple, one-time uploads with clean data. But you should consider Matrixify when:
Your file exceeds 15 MB: This app can handle file sizes up to 20 GB.
You need partial updates: With Shopify CSV, when you import, you either create new or replace existing Products (you cannot update, only replace); whereas with Matrixify you can update products as well. You can update even individual fields by importing just those fields.
You want to preserve product and variant IDs: With Shopify CSV, when you import your Products, the existing ones get deleted, and new are being created, which makes them have new IDs; whereas with Matrixify, when you import an update for the products, they keep the same ID.
You need metafield support: With Shopify CSV you cannot export or import Metafields. Whereas with Matrixify you can export Metafields as columns in the same table of Products.
You need import visibility: With Shopify you upload the CSV file and wait for e-mail. With Matrixify you see the progress of your imports/exports, estimated time to complete, and can cancel them any time.
The app will auto-detect CSV file encoding and automatically convert to UTF-8 as needed for Shopify. This alone eliminates one of the most common error categories before the import even begins.
View on app store