Shopify Product CSV Import Errors: Why Your Upload Failed (And How to Fix It)

Shopify lets you import products via CSV — which is great until you try it. You hit Import, watch the spinner, and get back a row-by-row report of failures. The error messages are unhelpfully generic: "Handle is invalid," "Cannot find variant," "Image could not be processed." The Shopify CSV format is rigid in ways that aren't obvious from the template, and most upload failures come from the same handful of issues.

How Shopify's Product Import Works

Shopify uses a single CSV format for products and their variants. Each product is one row plus additional rows for each variant. The Handle column links them: every row with the same Handle belongs to the same product. The first row with that Handle is the "main" row that holds product-level fields (Title, Body HTML, Type, Vendor, Tags). Subsequent rows with the same Handle hold variant-specific fields and are otherwise blank.

Get the Handle structure wrong and the importer either creates duplicate products, fails to link variants, or rejects the whole row. Most Shopify import errors trace back to Handle mistakes or variant column issues.

The Handle Column: Where Most Errors Start

What a Handle is

The Handle is the URL slug for the product (yourstore.com/products/the-handle). Shopify auto-generates one from the Title if you leave it blank, but if you specify a Handle in the CSV, it must follow Shopify's rules. Get one wrong and the row fails.

Invalid Handles:
Cotton T-Shirt          (spaces, uppercase)
cotton_t_shirt         (underscores)
CATEGORY/cotton-shirt  (slash)
-cotton-shirt-         (leading/trailing hyphen)

Valid Handles:
cotton-t-shirt
cotton-t-shirt-blue
limited-edition-cotton-shirt

Error: "Handle is invalid"

Run your Handle column through a quick check: lowercase everything, replace spaces and underscores with hyphens, strip non-alphanumeric characters except hyphens, and remove leading/trailing hyphens. This single transformation fixes the majority of Handle errors.

Error: "Handle already exists" or duplicate products

You're importing a Handle that matches an existing product in your store. Either rename the Handle to something unique, or use Shopify's update import flow (which updates the existing product instead of creating a duplicate). Note: Shopify treats Handles as case-insensitive when checking for duplicates, so "my-product" and "My-Product" collide.

Variant Errors: Where Things Get Tricky

Shopify supports up to three option dimensions (Size, Color, Material, etc.). The CSV has columns Option1 Name, Option1 Value, Option2 Name, Option2 Value, Option3 Name, Option3 Value. The product-level row (first row with a given Handle) defines the option names; every variant row specifies the values.

Error: "Variant Option Name mismatch"

The most common variant error. Shopify requires Option1 Name to be identical on every row with the same Handle. If the first row says "Size" and the third variant row says "size" (lowercase) or "Sizes" (plural), the whole product fails. This usually happens when CSVs are merged from multiple sources or edited row-by-row.

Wrong (Option Name varies):
Handle,Title,Option1 Name,Option1 Value
shirt,Cotton Shirt,Size,Small
shirt,,Size,Medium
shirt,,size,Large    <- lowercase 'size' breaks the product

Right:
Handle,Title,Option1 Name,Option1 Value
shirt,Cotton Shirt,Size,Small
shirt,,Size,Medium
shirt,,Size,Large

Error: "Duplicate variant"

Two variants share the same combination of Option1/Option2/Option3 values. "Size: Small, Color: Blue" can only appear once per product. Usually this happens when you've split a Size variant into separate rows but left the Color blank instead of duplicating it.

Error: "Cannot find variant" on update imports

When you import a CSV to update existing products, Shopify needs to match each row to an existing variant. It does this via Variant SKU. If the SKU in your CSV doesn't match any existing variant SKU, you get "Cannot find variant" and the row fails. Common causes: SKU got renamed in Shopify and the CSV is using the old SKU; the CSV has leading/trailing whitespace in the SKU column; SKUs differ in case (Shopify variant SKUs are case-sensitive).

Inventory Column Conflicts

Error: "Inventory Qty requires Inventory Tracker"

If you specify a value in Variant Inventory Qty, Shopify requires Variant Inventory Tracker to be set to "shopify" (case-sensitive). Leaving it blank or using "Shopify" with a capital S fails. If you don't want Shopify to track inventory for that variant, leave both columns blank.

Error: "Inventory Qty is invalid"

Shopify expects integers in Variant Inventory Qty. Decimals (5.0), text ("In Stock"), or empty cells with Inventory Tracker set to shopify all fail. If you genuinely have zero inventory, use 0, not blank.

Image URL Errors

Error: "Image URL could not be downloaded"

Shopify fetches every image URL during import. If the URL returns a 404, a redirect to a login page, or a non-image response, that image fails. Common culprits: Google Drive "sharing" links that require authentication, Dropbox links that aren't direct file links, image-hosting services that show a viewer page instead of the raw image, query-string-protected CDN URLs that have expired.

Error: "Image Position must be a number"

The Image Position column controls the order images appear on the product page. It must be an integer. The first image is Position 1, second is 2, etc. Don't leave it blank when an Image Src is set; don't put text like "first" or "main."

Multiple images per product

Each image is a separate row in the CSV with only the Handle and image columns populated (other columns blank). Many CSV builders forget this and try to comma-separate multiple image URLs in one cell — Shopify won't parse that. One image per row, same Handle linking them.

Field Length Limits

Error: "Title is too long"

Truncate to 255 chars. If you're importing from a marketplace export where titles include keyword stuffing, this is common — original titles like "Premium Organic Cotton T-Shirt for Men Women Unisex Casual Wear 100% Soft Breathable Crew Neck Short Sleeve Summer Spring Daily Wear" exceed the limit.

Metafield Column Issues

Shopify lets you import custom metafields via columns named like Metafield: namespace.key [type]. Getting the format right is fiddly: the namespace and key must already exist in your store's metafield definitions, the type must match, and multi-value metafields use a JSON array format.

Error: "Metafield definition not found"

Create the metafield definition in Settings > Custom data before importing. The column header must exactly match: same namespace, same key, same type bracket.

Encoding and Character Issues

Shopify expects UTF-8 encoded CSVs. Files saved from older Excel versions, exported from systems set to other regional encodings, or pasted from web sources often contain characters that look fine in your spreadsheet but break the import. The classic symptoms: accented characters appear garbled in the error report, product descriptions show as ?????? after import, the BOM (byte order mark) causes the first row to fail.

Step-by-Step: Fixing Your File

Step 1: Validate Handle column

Run every Handle through the rule check: lowercase, hyphens only, no leading/trailing hyphens. Convert any failures.

Step 2: Verify Option Name consistency

For each Handle, check that Option1 Name (and Option2/Option3 if used) is identical on every row. Identical means same casing, same spelling, same trailing whitespace.

Step 3: Check Inventory columns

If Variant Inventory Qty has a value, Variant Inventory Tracker must be "shopify" (lowercase). Decimals in quantity → convert to integers.

Step 4: Validate image URLs

Spot-check 5-10 image URLs by pasting them into a browser. They should return an image directly, not a viewer page. Replace any Google Drive or Dropbox sharing links with direct CDN URLs.

Step 5: Truncate over-long fields

Trim Title, Vendor, and Type to 255 chars. Drop tags beyond a reasonable count (50-100 is plenty).

Step 6: Fix encoding

Save as UTF-8 (without BOM) in a text editor. Replace smart quotes and em-dashes with ASCII equivalents.

Prevention: Export Discipline

If you're migrating from another platform (Etsy, Amazon, BigCommerce), the original export almost never matches Shopify's format. Build a per-source cleanup pipeline once and run it every time you import from that source. The biggest wins: a Handle normalizer (convert Title → valid Handle), an Option Name validator, and a UTF-8 encoder pass.