Skip to content

title: "Bulk import errors" description: "Bulk import reports errors at the row level and does not automatically fail an import due to individual row errors." This page defines how errors are struct...

Bulk import errors

Bulk import reports errors at the row level and does not automatically fail an import due to individual row errors.
This page defines how errors are structured, which categories exist, and how errors should be interpreted and handled operationally.

Errors may occur during both dry run and execution.

Error structure

Each error is associated with a specific row in a specific file.

An error record includes:

  • the target file
  • the row reference
  • the operation being executed
  • a descriptive error message
  • the phase in which the error occurred (dry run or execution)

Errors are collected independently per row and do not affect unrelated rows.

Structural validation errors are reported separately and block the import from proceeding.

Common error categories

Bulk import errors typically fall into the following categories:

Structural errors:

  • missing mandatory columns
  • invalid file names
  • unknown column names
  • invalid CSV structure or encoding

Identifier errors:

  • unresolved id or _id
  • missing identifiers for UPDATE or DELETE

Relation errors:

  • unresolved source or target rows
  • invalid relation API names
  • invalid link file structure for many-to-many relations

Data format errors:

  • invalid date or time formats
  • type conversion failures
  • invalid enum or constrained values

Structural errors block execution.
All other errors affect only the failing rows.

How-to

Related concepts