MindLab Future AIMost Shopify product CSV imports fail for a handful of reasons: product rows that don't share exactly the same Handle, image URLs Shopify can't fetch, two variants with the same option values, wrong column names, and the wrong file encoding or delimiter. Start from Shopify's own template, fix those five things, test with a few products first, then run the full file. The free checker below finds the common ones in your browser before you import.
Free Shopify CSV checker
Choose your product CSV or paste its contents. The check runs in your browser, and your file is not uploaded anywhere. It looks for the problems in this guide and lists them by row number (row 1 is the header).
This is a helper, not a guarantee. Shopify makes the final call on import, and its columns change over time, so keep Shopify's current template as your reference.
Handle mismatches
Shopify groups all rows with the same Handle into one product, and the first row carries the product details. When you update products, the handle is also how Shopify matches your row to an existing product. Two things go wrong:
- A typo or stray space on a variant row. “tee” and “tee ” are different handles, so that variant becomes its own product.
- Different capitalization. Treat handles as case-sensitive. Use lowercase letters and hyphens only.
Fix: copy the handle from the first row of each product down to every variant and image row, sort by Handle, and scan for near-duplicates. The checker flags handles that differ only by case or spaces.
Image URL errors
Shopify downloads images from the Image Src column during import. It can only fetch a URL that is public and points directly at an image file.
- Use a full address. Shopify's help page says the URL needs
http://in front of it. Test one sample row before a big import if you usehttps://, since Shopify's page words it that way. - No logins or private links. If the link needs a sign-in, or opens a share page (some Google Drive and Dropbox links do), the image won't import.
- Test in a private window. Paste each URL into an incognito window. If you see the image itself, Shopify can usually fetch it.
- Extra gallery images use extra rows. Repeat the same Handle and fill only Image Src (and optionally Image Position). Leave the other columns empty.
- Variant images are a separate column. Put the picture for one variant in Variant Image.
“Options are not unique”
This error means two variants of the same product have identical option values, such as two “Black / Medium” rows. The common causes are a duplicated row, the same Handle used by two different products, and trailing spaces that make two values look different when they aren't.
- Give every variant a different combination of Option1, Option2 and Option3 values.
- Fill Option1 Name (and Option2/3 Name if used) on the first row of each product.
- Search the file for the same Handle appearing in two separate blocks.
Headers, encoding and delimiter
- Start from Shopify's template. Export a few products from your store, or download the product CSV template from Shopify's import page, and paste your data into it. Don't retype headers.
- Keep header names exact. A column named “handle” or “Variant price” may be ignored. The checker flags headers that differ from the standard names only by case or spacing.
- Save as UTF-8. In Excel choose “CSV UTF-8 (Comma delimited)”. In Google Sheets, File, Download, Comma-separated values already saves UTF-8. Strange characters in names usually mean the wrong encoding.
- Use commas. Some regional Excel settings save semicolon-separated files. Shopify expects commas.
- Plain numbers for prices and quantities. No currency symbols or thousand separators.
A safe import workflow
Back up first
Export your current products before you import over them. Shopify has no built-in way to undo a saved bulk change that we could confirm, so the export is your rollback. More on undoing bulk edits.
Start from the template
Paste your data into Shopify's template columns.
Run the checker
Fix every error it lists. Review warnings and decide which apply to you.
Test with 5 to 10 products
Import a small file and open a few products to confirm variants, images and prices look right.
Import the full file
Then spot-check a sample against your spreadsheet.
Importing for a client? If you are a virtual assistant doing this for a store owner, ask for a staff or collaborator account with product permissions only, rather than a shared login. See how to give a VA safe access to your Shopify store.
FAQ
Why does my Shopify CSV import create a separate product for each variant?
Usually the Handle on the variant rows doesn't exactly match the first row of the product. A typo, extra space or different capitalization is enough. Copy the handle from the first row to every variant row.
Why are my images missing after a Shopify CSV import?
Shopify couldn't fetch the image from the URL in the Image Src column. The URL must be a full public web address pointing directly at an image, not a login-protected link or a share page. Test each URL in a private browser window.
What does the “options are not unique” error mean?
Two variants of the same product have the same option values, for example two “Black / Medium” rows. It can also be caused by a duplicated product block or by trailing spaces in option values.
Can I undo a Shopify CSV import?
Shopify has no one-click undo for a saved import or bulk edit that we could confirm. Export your products before importing so you have a file to restore from, and test with a small batch first. See our guide on undoing bulk edits and imports.
Is the CSV checker safe for client data?
The checker runs in your browser and does not upload your file to our servers. Still, only open client files you are allowed to handle, and delete local copies when you are done.
Want a hand with your Shopify store?
We build and fix Shopify stores, imports and integrations. Tell us what you are working on and we'll reply within 24 hours.
This guide is general information, not legal or security advice. Shopify's admin screens, limits and plan rules change, so confirm details in the Shopify Help Center. MindLab Future AI is not affiliated with Shopify.