Shopify CSV Handle Format: Common Errors & How to Fix Them

The Handle column is the most common source of Shopify CSV import failures. It's also the most confusing — because a wrong handle won't always show an error. Sometimes the import just silently skips the row.

What Is a Handle?

A handle is Shopify's internal identifier for each product — it becomes part of your product URL. For example, a product titled "Nike Air Max 90 Black" gets the handle nike-air-max-90-black and the URL yourshop.com/products/nike-air-max-90-black.

Handle Rules (Shopify's Actual Requirements)

Handles must follow these rules exactly. One violation and the row fails:

• Lowercase only. Nike-Air-Max will fail. Use nike-air-max.
• Letters, numbers, and hyphens only. No underscores, no spaces, no dots, no Chinese characters.
• No consecutive hyphens. product--name becomes product-name.
• No leading or trailing hyphens. -my-product- is invalid.
• Must be unique. Two products can't share the same handle.
• Every product row needs one. Blank Handle = skipped row.

Common Mistakes

1. Spaces in Handles

This is the #1 mistake. Excel exports from other platforms often include spaces. Shopify rejects them immediately.

2. Underscores Instead of Hyphens

3. Special Characters from Supplier Data

4. Uppercase Letters

5. Duplicate Handles

If rows 3 and 17 both have handle = "black-t-shirt", Shopify treats them as the same product. Row 3 imports fine. Row 17 silently fails — no error message, just missing from your store.

6. Chinese Characters

How to Auto-Fix Handles

Use CSVPreflight to validate and fix handles in one click. It auto-converts any handle to Shopify's format — spaces → hyphens, uppercase → lowercase, special chars removed, duplicates flagged.