Troubleshooting: Import Errors (CSV)

Common troubleshooting scenarios:

• Import validation failures
• Field mapping conflicts
• Invalid or missing required data
• Duplicate record handling
• Partial or failed imports

First question: where did it fail?

• Blocked before processing: usually CSV structure, missing required fields, or mapping issues.
• Failed during processing: row-level issues such as “not found” lookups, invalid values, or dependency constraints.

For the system-level explanation (queued processing, partial success, no rollback, recovery strategy):

• Import Processing Model (How Imports Behave)

Common errors (and what to do)

Missing required field / required column

• Cause: required column missing, blank required value, or required field not mapped.
• Fix: update CSV and/or mapping; re-run with corrected file.
• Prevention: use Prepare your CSV file for import.

Invalid value / invalid format

• Cause: type mismatch (date/number/boolean), inconsistent formatting, stray symbols.
• Fix: normalize formatting across the column; re-import corrected rows.

Lookup / reference “not found”

• Cause: your CSV references a value that doesn’t exist (or doesn’t match lookup rules exactly).
• Fix: create the referenced record first, or correct the lookup value to match existing data.
• Prevention: review Identifiers, Lookups, and Matching Rules.

Unexpected duplicates created

• Cause: identifiers missing/mismatched; rows were treated as creates.
• Fix: pause further imports; confirm matching logic; clean up duplicates; run targeted corrective updates if appropriate.
• Reference: Matching, Updates, and Safe Operation.

Best practice: correct only the failed subset

If some rows failed and others succeeded, do not re-run the full original CSV blindly. Instead:

1. Isolate the failed rows.
2. Correct values for those rows only.
3. Re-import the corrected subset.
4. Verify outcomes.

Verification workflow:

• Verifying imported data

Next step

• Verifying imported data
• Back to hub: Importing data into Administrate