Skip to main content

Troubleshooting: Import Errors

Updated

Purpose: Use this article to diagnose and resolve import validation failures, mapping issues, and processing errors.

This article explains common import problems and how to identify issues related to formatting, required fields, duplicate records, and field mapping conflicts.

Related workflows:

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):

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.

Lookup matched more than one record

  • Cause: the lookup value matches several records, so the row fails with an error like Lookup for field '…' with filter '…' and value '…' returned 2 results, expected 1. The import stops the row rather than picking one of the matches arbitrarily. A common example is two Course Templates sharing the same title.
  • Fix: use a unique supported identifier in the lookup column — Course Template lookups accept the course code or ID, which are unique — or make the ambiguous values unique (for example, rename one of the duplicate templates) before retrying.
  • Prevention: prefer codes and IDs over names and titles in lookup columns whenever records may share display names.

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.

Diagnose failures methodically

When an import reports errors, work from the failure results file rather than correcting the whole file at once:

  1. Download the failure results file. Its first column, Import Error, holds the error message for each failed row; the remaining columns preserve the original row data, so the file can be corrected and re-uploaded as-is.
  2. Start with the first failing row and read its error message; later rows often fail for the same reason.
  3. Check the basics for that row: required columns are mapped and populated, field types match (dates, numbers, booleans), lookup values exist and are unique, and there are no stray line breaks or quoting artefacts inside cells.
  4. Test small before retrying in full. Build a file containing the header plus one corrected failing row, import it, and only re-run the remaining corrections once that succeeds.
  5. If a value that looks valid still fails, keep the minimal file demonstrating the problem and send it to Administrate Support as a possible defect.

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:

Related articles