Catch CSV header and row errors before importing data

Start with a small, runnable preflight check

Download the Python script, synthetic CSV, and MIT license. The script uses only the Python standard library. It rejects duplicate or missing headers, checks two example fields, reports row numbers without echoing input values, and exits 2 when it finds invalid rows.

python3 csv-import-preflight.py csv-import-preflight.csv

This is the actual output from running those two downloadable files:

row 3: missing_product_code
row 4: invalid_stock
invalid_rows=2

Prefer to inspect the code before downloading? The same independent preflight example, synthetic input, and runnable tests are available in the public GitHub repository. The repository also shows the expected failure exit code and explains where this small check stops.

For your own importer, replace the example fields with your schema. Keep the original line number in errors, and decide whether the source file is allowed to have duplicate column names. A parser that silently keeps the last duplicate header can map values into the wrong target field.

Define the mapping before normalizing values

Map each source header to one target field explicitly. Then apply field-specific transforms: trim whitespace, parse an integer with bounds, normalize a date into an unambiguous form, and map known enum spellings. Reject unknown values rather than guessing. A price should be parsed with decimal semantics; a floating-point conversion can introduce rounding surprises.

Run row checks after normalization, so an empty value, bad number, duplicate key, or unsupported enum has a stable error code. Report row number, field, and code. Avoid copying confidential input values into a support log or downloadable error report.

Separate validation from importing

The free preflight script deliberately does not produce trusted application records or write to a database. A useful import boundary writes only validated normalized rows to a separate output, reports invalid rows, and lets the operator inspect counts before a downstream application import. Promotion into a live database needs its own authorization, transaction, rollback, and audit design.

What the source kits add

We ran BuildShelf's CSV Import Validator Mini against its included synthetic CSV. It produced two validated JSONL records, zero invalid rows, a source SHA-256 in report.json, and an empty value-free errors.csv:

{"active":true,"available":"2026-10-07","category":"hardware","price":"19.95","quantity":12,"sku":"SKU-001"}
{"active":false,"available":"2024-02-29","category":"software","price":"0.1","quantity":0,"sku":"SKU-002"}

The $19 Mini adds configurable header mapping, scalar normalization, row validation, within-file duplicate keys, clean JSONL, and safe error reports. It is a Python CLI source kit, not a browser UI. It does not parse XLSX or stage and promote data into a database.

The $249 full CSV / Excel kit adds restricted XLSX handling, SQLite staging, promotion, rollback, run history, and transactional audit. Choose that scope when a validated file alone is not a complete import workflow.

Compare the full CSV / Excel kit →

Disclosure: BuildShelf built and sells the linked source-code kits. The free script is independently usable under its MIT license. No customer data or paid kit source is included in the sample.