Why does the same handle appear on multiple Shopify CSV rows?

Rows with the same handle belong to one product. Repeating the handle is normal for variant rows, but using one handle for two unrelated products or duplicating the same option combination can cause import problems.

SHOPIFY CSV GUIDE

12 Shopify CSV import errors and how to fix them

Q: Which columns are required in a Shopify product CSV?

For new products, Shopify says Title is the only always-required column; URL handle is also required when adding variants. For product updates, URL handle and Title are required. Other fields can create dependencies, so include the related option and inventory columns when you update variant data.

A row-level error is usually easier to fix before upload than after a partial catalog import. Use this guide to diagnose the file first, then let Shopify perform the final store-specific checks.

Updated August 25, 20269 minute readBased on current Shopify Help Center guidance

Run a private CSV check

QUICK ANSWER

Start with structure, then product grouping, then field values.

01File structure

Keep Shopify’s headers, use comma-separated UTF-8, and repair stray quotes.

02Product grouping

Use one handle per product and unique option combinations for its variants.

03Field values

Check prices, inventory, statuses, policies, categories, and public image URLs.

COMMON ERRORS

What each message usually means

Invalid CSV header: missing headers

Required headers are missing, renamed, or padded with spaces

Shopify reads the first row as column names. A translated, misspelled, duplicated, or whitespace-padded header can prevent Shopify from mapping the file correctly. Current and older Shopify templates use some different names, and Shopify maintains backward compatibility with older names, but one file should use a consistent template.

Fix

Start with Shopify’s current sample product CSV or a fresh store export. Preserve the first row exactly, remove accidental spaces and duplicate columns, and avoid mixing current names such as URL handle with classic names such as Handle in the same file.

Illegal quoting on line

The file contains broken quotes or the wrong text encoding

Descriptions, tags, or titles that contain commas need correct CSV quoting. Smart quotes copied from a document editor, an unclosed quote, or a non-UTF-8 export can make one row spill into the next.

Fix

Export as UTF-8 comma-separated CSV. Replace curly quotes with straight quotes where they are acting as delimiters, then inspect the reported row in a plain-text editor for a missing or extra ". Do not remove valid quotes around cells that contain commas.

Ignored line … because it did not contain product data

The first product row has no title, or a variant cannot be linked to a product

For a new product, Shopify requires a title. Variant rows also need the product’s URL handle so Shopify knows which product owns the variant. Blank titles can be valid on continuation rows, but the first row of the group needs product identity.

Fix

Add Title to the first row of each product group. Repeat the same URL handle or classic Handle on every row that belongs to that product’s variants.

Ignored line … because handle already exists

One handle is being used for the wrong product group

A handle identifies a product, not an individual variant. Repeating it across that product’s variant rows is normal. Reusing it for an unrelated product, however, can merge data into the wrong group or conflict with an existing store product.

Fix

Give each distinct product one lowercase, hyphenated handle. Keep the handle identical only across rows that intentionally belong to the same product. When updating existing products, confirm the handle matches the product you intend to overwrite.

Validation failed: options are not unique

Two variants have the same option combination

Within one handle, each Size/Color/Material combination must identify one variant. Two rows for Medium + Black, or a duplicated product block elsewhere in the file, produces the same signature twice.

Fix

Sort or filter by handle, then compare Option1–Option3 values within that group. Remove the duplicate row or correct the option value that should be different. Keep option names consistent throughout the product.

Validation failed: price can't be blank

A variant price is empty or not a plain number

Price fields should contain numeric values in the store currency. Currency symbols, thousands separators, formulas, or text such as “Free” can fail validation even when they look reasonable in a spreadsheet.

Fix

Use a plain non-negative number such as 24.00. Remove $, €, £, and grouping commas. If you use a compare-at price for a sale, make sure it is higher than the selling price.

Inventory quantity can't be blank

Inventory fields conflict or the quantity is not a whole number

Inventory columns depend on each other. If Shopify is set as the tracker, related quantity, policy, and fulfillment values may also be required. Shopify’s classic inventory policy values are deny and continue.

Fix

Enter a whole number such as 0, 12, or -3. If inventory is not tracked, leave the tracker blank. If it is tracked, complete the related inventory fields and use the policy values expected by your CSV format.

Fulfillment service can't be blank

A tracked variant has no fulfillment service value

Related inventory fields can require a fulfillment service even when no third-party fulfillment app is involved.

Fix

Enter the exact configured fulfillment service. If the store fulfills the item normally and no external service is used, Shopify’s guidance says to use manual.

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

The image URL is malformed, private, redirected, or unavailable

Shopify must download product images during import. A local file path, sharing page, expired signed URL, blocked host, missing scheme, or nonexistent file can fail even when the spreadsheet displays it as a link.

Fix

Use a complete, publicly accessible direct image URL beginning with https://. Open it in a private browser window and confirm it displays the image without a login, cookie, or expiring permission.

Invalid value

Status or yes/no fields use unsupported labels

The current product status values are active, draft, and archived. Boolean columns expect true/false values rather than labels such as “Published,” “Yes,” or “Enabled,” unless the specific template says otherwise.

Fix

Use the values documented for that exact column and template. Normalize product status casing and convert clear boolean values to TRUE or FALSE.

Not a valid product category

The category does not exactly match Shopify’s taxonomy

Product category is not a free-form product type. Shopify expects either the complete category breadcrumb or a category ID from the Shopify Standard Product Taxonomy.

Fix

Copy the exact current breadcrumb or category ID. Put your own organizational label in the separate Type field instead of inventing a product category.

Value must be a valid product reference

A metafield references a product that does not exist yet

Product-reference metafields can only point to products that already exist in the store. A single import cannot reliably create a product and reference that new product before it exists.

Fix

Use two imports: first create the products without the reference values; then add the metafield values and import again with overwrite enabled. Review the overwrite preview carefully.

KNOW THE BOUNDARY

What can be checked before Shopify sees the file?

Merch Preflight checks locally

Missing or duplicate headers
Product titles and handle grouping
Duplicate variant combinations
Price, inventory, status, and policy formats
Image URL syntax and insecure HTTP links
Duplicate SKUs and barcodes

Shopify must check

Whether a remote image can be downloaded
Store taxonomy and metafield definitions
Existing product references and handles
Fulfillment services and location setup
Store-specific limits and platform changes
The final overwrite and import preview

Find deterministic errors before upload

Your catalog file stays in this browser.

Check my Shopify CSV

PRE-IMPORT CHECKLIST

Seven checks before you click Import

1
Export a backup
Keep a current product export before any bulk update.
2
Work on a copy
Preserve the untouched Shopify export for comparison.
3
Keep headers exact
Do not translate, merge, or casually rename columns.
4
Save as UTF-8 CSV
Use commas as separators and verify quotes around complex values.
5
Review dependent fields
Variant, inventory, and metafield columns often depend on related columns.
6
Run a private validation
Resolve blocking file errors before using a store import.
7
Read Shopify’s preview
Confirm creates, updates, and overwrites before committing.

FAQ

Shopify CSV import questions

Which columns are required in a Shopify product CSV?

For new products, Shopify says Title is the only always-required column; URL handle is also required when adding variants. For product updates, URL handle and Title are required. Other fields create dependencies, so include the related option and inventory columns when you update variant data.

Why does the same handle appear on multiple rows?

Rows with the same handle belong to one product. Repeating the handle is normal for variant rows. Using one handle for unrelated products—or repeating the same option combination—is the problem.

Can I edit the CSV in Excel or Google Sheets?

Yes. Export it as a comma-separated UTF-8 CSV, preserve Shopify’s column names, and check that quotes and commas inside cell values remain correctly escaped.

Does a clean report guarantee a successful Shopify import?

No. A local validator can catch deterministic file and catalog-data errors, but Shopify still performs store-specific checks such as remote image downloads, taxonomy references, metafield definitions, and current platform rules.

Official references

This guide was checked against Shopify’s current documentation on common product CSV import problems and using product CSV files. Shopify can change its formats and limits; use its import preview as the final authority.