Stop Guessing Why Your Shopify Product CSV Import Failed

q00tar00 — Sun, 28 Jun 2026 03:27:18 +0000

You exported a product CSV, edited it in Excel or Google Sheets, and uploaded it to Shopify.
Shopify shows a generic error — or worse, it silently imports the wrong thing: a handle gets
overwritten, a variant attaches to the wrong product, half your rows go missing. You find out
days later from a customer.

Shopify CSV Preflight Validator checks the file before you upload it. It runs locally on your
machine, never touches your store, needs no API key, and returns three things:

fixed_products.csv — a safe copy with the unambiguous, mechanical mistakes already corrected.
errors.csv — a machine-readable list of every finding (row, rule, severity, suggested fix).
report.md — a human-readable report you can read in 30 seconds.

No login. No upload of your catalog to a third party. Just a file in, a verdict out.

Why CSV imports fail (and why the error message doesn't help)

Shopify's product CSV import is a two-stage process: it validates the file, then applies rows.
A file can pass the upload dialog and still misbehave on apply. The most common ways merchants get
burned:

A spreadsheet adds a UTF-8 BOM to the first cell. The first header (Title) becomes invisible-garbage + Title, so Shopify can't find the title column.
Header case / legacy names drift. title instead of Title, Handle instead of URL handle. Some get ignored, some get rejected.
A variant row loses its parent handle. Shopify can't tell which product the variant belongs to.
Two product rows share one handle. Shopify silently keeps one and overwrites/merges the other.
Image alt text with no image URL, negative prices, compare-at prices below the real price — small data bugs that ship to your live storefront.

These are not exotic. They're what happens every time a human edits a CSV in a spreadsheet.

What the tool actually does — a real run

Here is a messy export with several of the problems above. Running:

csv-preflight check messy-product-import-sample.csv --out-dir ./out --lang en

produces this report.md (verbatim):

# Shopify CSV Preflight Report

- Summary: scanned rows 4 / product groups 3 / 6 critical / 8 warning / 2 auto-fixed (proven) / 1 suggested

## Critical (fix before import)
- [F01a] file: UTF-8 BOM detected at file start.
- [F03a] file: Header 'title' differs only by case from a known column.
- [R02] row 2: Variant/image row is missing the parent URL handle.
- [R03] row 1: 2 product-start rows share handle 'aurora-hoodie' (rows 1, 3).
- [R03] row 3: 2 product-start rows share handle 'aurora-hoodie' (rows 1, 3).
- [R11] row 4: Image alt text present but image URL is empty.

## Warning (review recommended)
- [R07] row 4: inventory_policy 'maybe' is not a documented value (deny/continue).
- [R08] row 4: Inventory tracker 'shopify' set but inventory quantity is empty/non-numeric.
- [R10] row 1: Compare-at price 3900.0 <= price 4800.0.
- [R10] row 4: Price '-1800' is negative.
- ... (fulfillment-service defaults, etc.)

## Auto-fixed (proven)
- [F01a] file: UTF-8 BOM detected at file start.
- [F03a] file: Header 'title' differs only by case from a known column.

## Not checked
- Not checked by this tool: image URL public reachability, handle overwrite/ignore
  against an existing store, metafield product reference resolution, and option position
  consistency with existing products.

The exit code is non-zero when criticals are present, so you can wire it into a script and stop
a bad upload automatically.

What got fixed automatically

Two classes of mistake are unambiguous and safe to fix mechanically, so the tool writes them into
fixed_products.csv for you:

BOM removed from the file start.
Header case normalized (title → Title).

Everything else — missing handles, duplicate handles, negative prices — is a judgment call, so the
tool reports it but never silently rewrites your data. You stay in control of your catalog.

Honest about its limits

The report always prints a Not checked section. The tool reads a file; it does not connect to
your store. It cannot know whether an image URL is publicly reachable, whether a handle will
overwrite an existing product, or whether a metafield reference resolves. It says so, every time.
We would rather under-promise than tell you "import guaranteed" and be wrong.

Who this is for

Solo merchants doing a bulk product update before a launch or sale.
Agencies / freelancers migrating a client's catalog and wanting a clean handoff.
Anyone who has been burned once by a silent partial import and never wants to guess again.

It is product CSV only. It deliberately refuses files that look like order or customer exports
(it detects buyer-PII column names and stops) — your customers' data never goes through it.

How it compares

The existing tools (Matrixify, Ablestar) are powerful full migration suites. Merchants who don't
need all of that consistently say the same three things: expensive, slow, and hard to learn.

This tool is the opposite end: one command, one purpose — catch the import-breaking mistakes before
you upload — with no account and no upload of your catalog.

	Full migration apps	CSV Preflight Validator
Setup	Install app, connect store	Run one command locally
Touches your store	Yes (Admin API)	No — file in, file out
Your catalog leaves your machine	Often	Never
Job	Migrate everything	Stop a bad import

Try it

It's on GitHub — read the source, grab a release, run it on your own file:

https://github.com/q00tar00/shopify-csv-preflight

uv tool install csv-preflight
csv-preflight check your-products.csv --out-dir ./out

If a silent partial import has ever bitten you, I'd love to hear what broke — drop a comment or open
an issue. I'm validating whether this is worth turning into a paid one-shot / Shopify app, and real
merchant pain is exactly what I'm looking for.

DEV Community: q00tar00