Troubleshooting · verified 2 August 2026

Why does a Shopify product CSV import fail?

A Shopify product CSV commonly fails because the first row has unmatched headers, the delimiter or quoting breaks row structure, a required/dependent field is absent, a price contains non-numeric text, an enum value is unsupported, or a remote image/product reference cannot be used. Start with the exact Shopify error, then check the affected row rather than rewriting the whole file.

Why does Shopify ask me to choose column headings?

Shopify says this appears when CSV headers are incorrect. Hidden spaces, older names, duplicates, or a supplier's custom columns can trigger a mismatch. CatalogVigil shows the raw header and the recognised current/legacy equivalent.

Compare the first row with a fresh Shopify export from the target store. Do not rename a supplier column only because it looks similar: a header is a contract about the meaning of every cell beneath it. If both a current and legacy equivalent exist in one file, decide which column is authoritative before importing.

Why are there random characters in the import?

Shopify supports UTF-8 and attributes strange characters to a non-UTF-8 file. Re-export as UTF-8, preserve the original, and verify non-English product text before upload. CatalogVigil reads browser text and produces UTF-8 corrected downloads, but cannot recover characters already corrupted before the check.

Also check whether the export used semicolons instead of commas and whether a description contains an unclosed quotation mark. A malformed quote can make several physical lines parse as one cell. The encoding and quoting guide shows how to trace the first broken field.

Why is a price rejected?

Price fields should be plain numeric values rather than currency-formatted spreadsheet strings. CatalogVigil flags currency symbols, thousands separators, and text, but does not strip them automatically because locale punctuation can change the amount.

Why does one row have too many or too few fields?

Every parsed row must align with the header count. Extra fields often come from unquoted commas; missing fields often come from manual deletion or broken quotation. Work from the first malformed row because later-looking failures may simply be consequences of an earlier unclosed field. Compare against the source record rather than padding or deleting columns by eye.

Why are variants lost or recreated?

Variant columns depend on option names and values. Changing option values can also create new variant IDs, which can break third-party dependencies. Review the variant option dependency before updating.

Why do images fail when their URLs look correct?

Shopify fetches the remote image. A string can look like a valid URL but lead to a login page, an expired signed link, an HTML response, a rate limit, or a host that blocks automated requests. Test new image URLs without being signed in, keep additional image rows attached to the correct handle, and use a staged import. See the product image guide.

Why does Shopify report an invalid product or metafield reference?

Some fields refer to objects or definitions that exist in the store. A local file checker cannot confirm that a product, collection, inventory location, market, or metafield definition is present and compatible. Use Shopify's exact message to find the row, compare the reference with the target store, and avoid copying dynamic columns blindly from another store.

What order should I troubleshoot in?

1. Preserve the original and reproduce the error with a small copy.
2. Fix file-level problems first: encoding, delimiter, unmatched quotes, and row widths.
3. Then fix headers and create/update required fields.
4. Review variant dependencies before product values.
5. Inspect numeric, enum, URL, and reference errors at the reported row.
6. Re-run the preflight after each coherent change set.
7. Use Shopify's preview and verify the staged result before a full import.

Can a preflight catch every error?

No. Store state, product/metafield references, remote image responses, app relationships, market configuration, and platform-side limits require Shopify's own validation. Use CatalogVigil as a deterministic local preflight, not a guarantee.

Primary sources: Shopify common product CSV problems and product CSV format.