Troubleshooting: Import Errors

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?

• Flagged during validation: most file structure, required field, formatting, and mapping issues are caught before the import runs. You can fix these directly on screen, or correct your file and re-upload it.
• Failed during processing: row-level issues such as "not found" lookups or dependency constraints, which can't be fully validated before the import runs.

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: blank required value, or a required field not mapped. If a required column is missing entirely, Administrate adds it automatically and marks it as required during mapping.
• Fix: populate the required value or complete the mapping, then re-validate. You can correct this on screen or by re-uploading a corrected file.
• Prevention: use Prepare your file for import.

Invalid value / invalid format

• Cause: type mismatch (date/number/boolean), inconsistent formatting, stray symbols, or values such as invalid email addresses or incorrect country/province codes.
• Fix: many common formatting issues are flagged during validation and can be corrected on screen. Where possible, use the dropdowns in our Excel template to enter valid values.

Lookup / reference "not found"

• Cause: your file references a value that doesn't exist (or doesn't match lookup rules exactly). Lookup fields can't be validated before the import runs, so these surface as row-level errors during processing.
• Fix: create the referenced record first, or correct the lookup value to match existing data.
• Prevention: before running your import, confirm that any values used in lookup fields already exist in your Administrate instance. See 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 file 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