Guide · Shopify CSV Handle Errors

Shopify CSV Handle Errors
How to fix missing, duplicate, and invalid handles.

We’ve watched this happen in real time. A merchant uploads a 2,000-row CSV to Shopify. Shopify accepts it without complaint. They click import, see a green success message, and move on.

Two weeks later they notice their sitemap has URLs like /products/product-1 and /products/unnamed-item-3. Google traffic is down 40%. Every one of those products was supposed to have a clean, keyword-rich URL.

⚠
Handle errors don’t crash imports. They damage them silently.

By the time you notice, the products are live, indexed, and linked. Fixing them means breaking URLs.

What is a Handle in a Shopify CSV?

A handle is the URL slug for a product. When you create a product called “Blue Cotton T-Shirt,” Shopify generates a handle like blue-cotton-t-shirt. That handle becomes the product’s permanent URL: https://yourstore.com/products/blue-cotton-t-shirt.

In the CSV, Handle is the column Shopify uses to match rows to products. It’s the only column Shopify uses for matching. Not SKU. Not barcode. Not title. Handle.

This means two important things:

  • If the handle is wrong, Shopify either creates a duplicate product or fails to update the one you meant to update.
  • If the handle is blank on an update import, Shopify matches it to nothing — and either skips the row or creates a new product with a garbage URL.

The three handle errors that break imports

1. Missing handles

The most common. Your CSV has rows with nothing in the Handle column.

On a new-product import: Shopify creates the product, but generates a placeholder handle from the title. If the title contains special characters (like —, &, or non-English letters), the generated handle can be unpredictable. If the title is also blank, the handle becomes product-1, product-2, etc.

On an update import: Shopify can’t match the row to anything. Depending on your CSV structure, it either skips the row entirely or creates a duplicate product. This is how merchants end up with two versions of the same product in their store — one clean, one from the CSV.

2. Duplicate handles

Two rows with the same handle. What happens next depends on the titles.

Same title on both rows: Shopify treats them as variants of the same product. This works if you’re actually importing variants (Size: Small, Size: Medium, etc.). If you accidentally duplicated a row, one variant silently overwrites the other.

Different titles on both rows: Shopify merges them into a single product. The last row’s values win. If both rows had different prices, only one survives — and you have no idea which.

3. Invalid handle format

Shopify handles must be lowercase, use hyphens between words, and contain only letters, numbers, and hyphens. No spaces, no underscores, no uppercase, no accents.

If your CSV has Blue T-Shirt in the Handle column, Shopify will reject the row or auto-fix it depending on the import method. If it’s blue_t_shirt (underscores), Shopify may accept it but the URL breaks in some browsers. If it has special characters like café-mug, the handle survives import but breaks links elsewhere.

The rule: ^[a-z0-9]+(-[a-z0-9]+)*$ — lowercase letters, numbers, hyphens between. Nothing else.

How to fix each error

Fixing missing handles

The safest fix is to generate them from the product title. The logic:

  1. Take the Title
  2. Convert to lowercase
  3. Replace spaces with hyphens
  4. Remove any character that isn’t a letter, number, or hyphen
  5. Collapse multiple hyphens into one
  6. Trim leading and trailing hyphens
Blue Cotton T-Shirt — Premium
→
blue-cotton-t-shirt-premium

Edge cases worth knowing:

  • Non-English characters: Café should become cafe (accents stripped and transliterated, not dropped). Some tools produce caf, which looks broken in URLs.
  • Emoji in titles: strip them entirely. Shopify will reject emoji in handles.
  • Duplicate titles: append -2, -3 to make handles unique. Otherwise Shopify silently merges the products.

Fixing duplicate handles

If two rows share a handle, figure out which case you’re in:

  • They’re actual variants (Size: Small, Size: Medium). Then it’s not an error — keep the same handle on both rows and make sure the variant columns (Option1 Name, Option1 Value) are correctly filled.
  • They’re two different products that got the same handle by mistake. Rename one. If blue-tee appears twice with different titles, the second one becomes blue-tee-v2 or something specific to its actual content.
  • One is a duplicate paste. Delete the duplicate row.
🛑
Shopify won’t warn you.

Duplicate handles either merge or drop without notification. The import still reports “success.” You only notice days later when products are missing.

Fixing invalid handle format

Normalize using the same transform you’d use for generating a handle:

Blue T-Shirt
→
blue-t-shirt
blue_shirt
→
blue-shirt
Café Mug
→
cafe-mug
mug—large
→
mug-large
💡
Normalize before your first import. Never after.

If you already imported a product with handle blue-t-shirt and now update it with a row containing Blue T-Shirt, the handles don’t match. Shopify sees them as different products. You’ll get a duplicate. Fix handles on the source file, not after import.

How to prevent handle errors before import

Before any import, check your CSV for:

  1. Rows with blank Handle cells — these will create or merge unpredictably.
  2. Duplicate handles with different titles — these will merge into one product.
  3. Handles with spaces, uppercase, underscores, or special characters — these will break URLs.

You can do this manually with Excel filters. Or you can scan the file once with a tool that does all three checks in a single pass.

Check your CSV handles in 30 seconds

Autonom Shopify Guard scans every handle in your file — missing, duplicate, or invalid — before you upload it. Free, browser-based, no account needed.

Open Shopify CSV Validator →

Related guides

Frequently asked questions

Can I leave the Handle column blank on a new-product import?

Yes, but not recommended. Shopify will auto-generate a handle from the title, which sometimes produces unexpected slugs. Always define handles explicitly.

What happens if I import a CSV with handles that don’t match any existing product?

Shopify creates a new product. It does not fail the import. This is how merchants accidentally create duplicates when they meant to update.

Can I change a product’s handle after it’s been imported?

Yes, but the old URL will 404. Shopify automatically redirects some cases but not all. If your product has external links pointing to it, consider whether the handle change is worth breaking them.

Are Shopify handles case-sensitive?

No. Blue-Tee and blue-tee resolve to the same URL. But Shopify normalizes on import, so always use lowercase to avoid surprises.

What’s the difference between Handle and URL?

Handle is the CSV column name. URL is the full address (yourstore.com/products/handle). Same concept, different context.

Scroll to Top