Shopify CSV Variant Errors
How orphaned rows, duplicate combinations, and collapsed products destroy catalogs.
Variants are the most fragile part of a Shopify CSV. A single misaligned column, one missing Option value, or a duplicate row can cause Shopify to silently drop every variant on a product — leaving only the parent row behind. No error message. No warning. Just a product that used to have sizes and colors, now alone.
This guide covers the seven variant errors that break imports, what Shopify does with each one, and how to catch them before they hit your store.
It merges, drops, or replaces rows silently. If your CSV has a variant error, you find out days later when customers can’t select a size.
How Shopify reads variants in a CSV
Every variant of a product shares the same Handle. The first
row with a handle is the parent row (contains the product Title, Body HTML,
etc.). Every subsequent row with the same handle is a variant — differentiated
by Option1 Value, Option2 Value, and
Option3 Value.
Shopify identifies each variant by the combination of Option values. Small/Red, Small/Blue, Medium/Red, etc. Each combination must be unique within the product.
If Shopify can’t read the row as a valid variant of the parent, it either creates a standalone product, merges it with another row, or drops it entirely. You don’t get to choose which.
The seven variant errors that break imports
1. Orphaned variant rows
A row has variant data (SKU, price, Option1 Value) but no Handle. Without the handle, Shopify can’t attach the row to any product.
What happens: The row is either skipped silently or treated as the start of a new product. Either way, you lose the variant from the parent.
2. Duplicate option combinations
Two rows of the same product have the same combination of Option values. Example: two rows both saying “Small / Blue.”
What happens: Shopify silently drops one of the rows. You think you have two variants; you actually have one. Prices and SKUs from the dropped row vanish.
3. Incomplete option pairs
A row has Option1 Name but no Option1 Value
(or vice versa). Or Option2 has a name but Option1 is blank.
What happens: Shopify treats the incomplete pair as invalid. It may:
- Drop the entire variant row
- Ignore the option but keep the row as a duplicate of the parent
- Reject the import for the whole product
4. Column inconsistency across variant rows
Some variant rows fill Option1 Value and Option2 Value.
Others fill only Option1 Value. Shopify sees an inconsistent
product structure.
What happens: Shopify picks one interpretation and collapses the product. This is the error behind most “my variants disappeared” reports.
5. Inconsistent option names
Variant rows of the same product use different names for the same
option. One row says Option1 Name: Size, another says
Option1 Name: Size Range.
What happens: Shopify can’t resolve the variant relationships. All variants of the product get merged into one, or the entire product row set is rejected.
6. Missing Option1 declaration on multi-image single-variant products
A product has one variant but multiple images (image rows with just
Handle + Image Src). Without Option1 Name: Title and
Option1 Value: Default Title on the parent, Shopify
treats each image row as a duplicate variant.
What happens: Shopify creates three “products” that are all the same product. Or drops the extra image rows.
7. Image rows with stray variant data
An image row (meant to be just Handle + Image Src) has values in Option1 Value, Variant Price, or Variant SKU.
What happens: Shopify interprets the row as a variant with a new option combination, even though it’s supposed to be an additional image. You get phantom variants.
What a well-formed variant block looks like
Here’s what a valid Shopify CSV looks like for a product with three variants:
What makes it valid:
- Every row uses the same
Handle(blue-tee) - Every row has the same
Option1 Name(Size) - Every row has a unique
Option1 Value(Small, Medium, Large) - Only the first row has a Title (it’s the parent)
- Every row has its own SKU and price
Now the same product, broken:
Three errors in three rows:
- Row 2 and Row 3 are duplicates — both are “Small.” Shopify drops one silently.
- Row 4 has no Handle — it’s an orphaned variant. Shopify ignores it or creates a duplicate product.
- The product now only has one valid variant (Small) instead of three.
How to check your variants before import
Before any import, scan for these three signals:
Signal 1 — Orphaned rows
Sort your CSV by Handle. Any row with a blank Handle but non-blank SKU, price, or option value is orphaned.
Signal 2 — Duplicate option combinations
Group rows by Handle. Within each group, look at the combination of Option1 Value + Option2 Value + Option3 Value. Any duplicate combination means Shopify will silently drop one.
Signal 3 — Column inconsistency
Within each Handle group, check that every variant row fills the same option columns. If row A has “Option1 Name: Size” and row B has no Option1 Name at all, the product structure is inconsistent.
Manual checking works for 20-row files. It does not work for 2,000-row files with multiple products. There’s too much to hold in your head.
Scan every variant in 30 seconds
Autonom Shopify Guard checks every variant row for all seven errors above — orphaned rows, duplicates, incomplete pairs, and column inconsistencies. Free, browser-based, no account needed.
Open Shopify CSV Validator →Related guides
Frequently asked questions
Can I have multiple variants without an Option1 Name?
No. Shopify requires Option1 Name and Option1 Value on every variant row. Without them, Shopify can’t distinguish your variants and treats the extra rows as duplicates.
What’s the maximum number of variants per product in Shopify?
Shopify supports up to 100 variants per product on standard plans. Shopify Plus supports up to 2,000. The 3-option structure (100 × 100 × 100) is a hard limit on the option matrix.
Why did my variants disappear after import?
The most common cause is duplicate option combinations or column inconsistency. Shopify picks one interpretation and drops the others. Check the CSV for rows with the same Handle and the same option values.
Can I update a single variant without touching the others?
Yes, but you need to include every variant row of that product in the CSV. Shopify replaces the entire variant set when you update a product. If you only include one variant row, Shopify may delete the others.
Do variants need the same Handle or the same Title?
Both must match. Every variant row must have the same Handle. Only the first (parent) row should have a Title. Non-parent rows should leave Title blank — filling it creates ambiguity.
What does “Option1 Name: Title / Option1 Value: Default Title” mean?
It’s how Shopify represents a single-variant product. When a product has one variant but needs to be recognized as a variant (to allow multiple images), you set Option1 Name to “Title” and Option1 Value to “Default Title.” This is standard on Shopify exports.