CSV Import Error? Diagnose the Exact Problem in 60 Seconds
You upload your CSV. Something goes wrong. The error message says "Invalid file format" — but the file opens fine in Excel. Or the import says "Success" — but half your records are blank. Or the tool just stops at row 1 with no explanation at all.
The instinct is to start fixing things: re-save the file, change the encoding, re-export from the source. That approach works eventually, by accident, after an hour of trial and error.
There's a faster way. CSV import failures fall into a small number of distinct error types, each with a clear symptom pattern. Once you know which type you have, the fix is usually under 5 minutes. Without that diagnosis, you're guessing.
This guide walks you through the 3-tier diagnostic framework we use to classify every CSV error — and routes you directly to the right fix guide for each one.
If you want automatic diagnosis without working through it manually, run your file through the Data Validator — it detects delimiter, encoding, structure, and format errors in under 4 seconds (results vary based on file size and device), client-side, with no upload required.
For the complete reference of all CSV import failure types, see our CSV import errors complete guide.
Table of Contents
- Why Won't My CSV Import?
- The 3-Tier Diagnostic Framework
- How to Read a CSV Error Message
- Tier 1: Import Refuses to Start
- Tier 2: Import Starts But Fails Mid-Process
- Tier 3: Import Says Success But Data Is Wrong
- The 60-Second Diagnostic Checklist
- When the Error Message Is Missing Entirely
- FAQ
Why Won't My CSV Import?
Most failed CSV imports trace back to one of three root causes:
- File-level errors — encoding, delimiter, or BOM issues that prevent the platform from reading the file at all
- Data-level errors — invalid values, column mismatches, or structural problems that cause the import to fail mid-process
- Silent corruption — invisible whitespace, wrong date formats, or stripped leading zeros that let the import "succeed" while quietly corrupting your data
The diagnostic framework below helps you identify which category you have in under a minute — and routes you directly to the right fix.
The 3-Tier Diagnostic Framework
Every CSV import failure fits into one of three tiers based on when and how it fails. Identifying the tier takes about 10 seconds and immediately eliminates 60–70% of possible causes.
Tier 1 — Import refuses to start. The platform rejects the file immediately on upload. You never get past the file selection or the first validation step. Error messages tend to be about the file itself: encoding, format, file type.
Tier 2 — Import starts but fails mid-process. The platform accepts the file and begins processing, but stops at a specific row or hits an error count limit. Error messages usually reference specific rows, columns, or field values.
Tier 3 — Import says "Success" but data is wrong. The most dangerous tier. The import completes without any error — but field values are blank, records are duplicated, lookup fields didn't match, or row counts don't add up. No error message to diagnose from.
[Screenshot: Three-tier decision tree — Tier 1 file rejected, Tier 2 fails at row X, Tier 3 silent success with corrupt data]
The tier tells you where the problem lives:
- Tier 1 → problem is in the file structure or encoding
- Tier 2 → problem is in the data values or row structure
- Tier 3 → problem is in invisible formatting (whitespace, line endings, leading zeros, encoding edge cases)
For first-time imports from a new data source, Tier 1 errors tend to be the most common starting point — file structure and encoding issues are the first thing a platform checks before it processes a single row of data.
About this framework: The 3-tier model was developed by analyzing CSV import failures across CRM platforms, databases, and accounting tools — including Salesforce, HubSpot, MySQL, Snowflake, and QuickBooks. While each platform uses different error messages, the underlying failure patterns are consistent across CSV parsers. The framework categorizes failures based on where in the import pipeline they occur.
How to Read a CSV Error Message
If your platform gave you an error message, start here. Different platforms use different terminology for the same underlying problem — this translation table maps the most common messages to their actual cause.
| Platform says... | What it actually means |
|---|---|
| "Invalid CSV file format" (Salesforce) | Encoding issue, BOM character, or unescaped quote breaking row structure |
| "Field mapping failed" (HubSpot) | Header name has whitespace, special character, or doesn't match expected property name |
| "Bad value for restricted picklist" (Salesforce) | Picklist value has a trailing space, wrong case, or simply doesn't exist in the allowed list |
| "1064 syntax error at line 1" (MySQL) | Usually a delimiter mismatch or unescaped quote in the first data row |
| "Columns do not match" (Snowflake) | Column count in a data row doesn't match the header — often caused by an unescaped comma in a field |
| "Invalid date format" (Airtable) | Date written in a format the platform doesn't recognise (e.g. DD/MM/YYYY when MM/DD/YYYY expected) |
| "Continue button grayed out" (QuickBooks) | Required field missing, wrong data type, or encoding issue preventing validation from completing |
| "Upload failed" (generic) | File-level rejection — check encoding, delimiter, and BOM first |
[Screenshot: Salesforce Data Loader error log showing error types, row numbers, and field names — sorted by error type column]
If your error message isn't in this table, or you have no error message at all, use the tier-by-tier breakdown below.
Tier 1: Import Refuses to Start
The file gets rejected before any data is processed. Match your error message or symptom to the cause:
| Error message / symptom | Most likely cause | Fix guide |
|---|---|---|
| "Invalid file format" or "Not a valid CSV" | File is not UTF-8, or has BOM characters | BOM CSV fix guide |
| "Could not detect delimiter" | File uses semicolons or tabs, not commas | CSV delimiter fix guide |
| "All data in one column" | Delimiter mismatch — European format semicolons | CSV opens in one column fix |
| "Encoding error" or garbled characters on preview | File is ANSI/Windows-1252, not UTF-8 | CSV encoding fix guide |
| "Missing header row" or "No column names found" | Header row absent or in wrong position | CSV missing header fix |
| Upload completes but import won't proceed | File has BOM byte (EF BB BF) at start | BOM CSV fix guide |
The fastest Tier 1 diagnostic: Open your file in a plain text editor (Notepad on Windows, TextEdit in plain text mode on Mac). If you see strange characters at the very start of the file, that's a BOM. If all your data is on one line, your line endings are wrong. If the first row has no commas, your delimiter is wrong.
[Screenshot: Notepad showing CSV file — top row visible with semicolon delimiters and garbled first characters indicating BOM]
Tier 2: Import Starts But Fails Mid-Process
The platform accepts your file and begins importing, but stops with an error at a specific row or field. These are the most informative errors because the platform usually tells you exactly where it failed.
| Error message / symptom | Most likely cause | Fix guide |
|---|---|---|
| "Invalid data type" / "Expected number, got text" | Text in a number, date, or boolean field | CSV data type mismatch fix |
| "Bad value for restricted picklist" | Trailing space or case mismatch on picklist value | CSV whitespace fix |
| "Column count mismatch" / "Wrong number of fields" | A row has more or fewer columns than the header | CSV column count mismatch fix |
| "Unexpected rows" / "Extra rows detected" | Empty rows between data, or wrong line endings | CSV empty rows fix |
| "Rows merged" / parser stops mid-file | CRLF/LF line ending mismatch | CSV line break error fix |
| "Maximum error count reached" | Multiple field-level errors across many rows — Salesforce Data Loader stops by default at 200 field errors, meaning the rest of your file was never processed | Run Data Validator for full error report |
| "Unmatched quote" / "Unexpected end of record" | Unescaped double quotes in a field value | CSV escaped quotes fix |
Reading Tier 2 error logs: Most platforms — Salesforce Data Loader, HubSpot, MySQL — produce an error file after a failed import. Download it. The error log tells you the row number, the field name, and the error type. Sort by error type, not row number — if the same error appears on 500 rows, fixing the root cause once fixes all 500.
Tier 3: Import Says Success But Data Is Wrong
This is the hardest tier because there's no error message to read. The import completed — it just didn't do what you expected. The diagnosis requires comparing what you sent versus what arrived.
| Symptom | Most likely cause | Fix guide |
|---|---|---|
| Field values blank after import | Leading/trailing whitespace stripped to nothing | CSV whitespace fix |
| Leading zeros missing (01234 became 1234) | Platform treated number-format field as integer | CSV leading zeros fix |
| Lookup fields didn't match / joins failing | Whitespace or encoding difference in key field | CSV whitespace fix |
| Deduplication created false duplicates | Invisible space making two identical values distinct | CSV whitespace fix |
| Row count after import doesn't match file | Empty rows counted, or rows silently rejected | CSV empty rows fix |
| Dates imported as wrong values | Date format mismatch (MM/DD vs DD/MM) | CSV mixed date formats fix |
| Numbers imported in scientific notation | Platform auto-formatted long numeric strings | CSV leading zeros fix |
The Tier 3 diagnostic approach: Export 5–10 records from the destination after import and compare them against the original CSV side-by-side. Check the fields that look wrong in a plain text editor (not Excel — Excel hides whitespace and reformats numbers). The gap between what you sent and what arrived is your error type.
The 60-Second Diagnostic Checklist
Work through this in order. Stop at the first item that matches your situation — that's your error type.
Step 1 — Did the import reject the file immediately? → Yes: Go to Tier 1 table above. Open file in plain text editor and check the first line.
Step 2 — Did the import start but fail at a specific row or field? → Yes: Go to Tier 2 table. Download the error log if available. Sort errors by type.
Step 3 — Did the import say "Success" but the data looks wrong? → Yes: Go to Tier 3 table. Export 5 records from the destination and compare to your CSV.
Step 4 — No error message at all, import just hung or timed out? → Try splitting the file into smaller chunks first using the CSV Splitter. If a smaller split imports successfully, the issue is file size or a platform row limit — not your data format.
Step 5 — Still can't tell? → Run the file through the Data Validator. It scans for all known error types — delimiter, encoding, structure, whitespace, column count, line endings — in a single pass and tells you exactly what it found. For the full taxonomy of every error type this checklist covers, see our CSV import errors complete guide.
When the Error Message Is Missing Entirely
Some platforms — particularly older CRMs, legacy ERP systems, and basic import tools — give you nothing. The import fails, or produces wrong data, with no error code, no row reference, and no log file.
Before running the checks below: if your file won't open at all — not even in a text editor — you have a Tier 0 problem. The file is corrupted or is not a real CSV (e.g. a binary export mislabeled as .csv). Try re-exporting from the source system before anything else.
In these cases, the diagnostic order is:
1. Check encoding first. Open the file in a text editor. If you see é instead of é, or “ instead of ", you have an encoding mismatch. The file needs to be saved as UTF-8. This is the single most common cause of platform-agnostic import failures.
2. Check the delimiter. In the text editor, look at how values are separated. If you see semicolons, tabs, or pipes instead of commas, your platform may be trying to parse a semicolon-delimited file as comma-delimited.
3. Check line endings. If your entire file appears on one line in the text editor, your line endings are wrong. See the CSV line break error fix guide.
4. Check column count consistency. Count the commas in the header row. Count the commas in row 2. If they're different, you have a structural column mismatch — often caused by an unescaped comma inside a field value.
5. Validate with a tool. The Data Validator runs all five checks above in one pass and reports results without requiring you to upload your file to any server.