Validation Rules & Error Handling¶

Before any data transformations occur, the Loader validates your CSV data and configuration against entity-type-specific rules. This page documents the validation checks, common error messages, and how errors and warnings are reported.

How Validation Works¶

Validation runs as Phase 2 of the preprocessing pipeline, after CSV parsing but before any data transformations. The validator checks:

Configuration completeness -- Is the config present and properly structured?
Required fields -- Are all required fields available (via CSV headers, federated mappings, or conditional columns)?
Type path validity -- Does the typePath match the expected format for the entity type?
Data integrity -- Are there duplicate federated IDs, conflicting values, or empty required fields?

If validation produces any errors, the load stops immediately with a VALIDATING_DATA failure area. Warnings allow the load to continue.

Where Required Fields Can Come From¶

Required fields don't have to be literal CSV column headers. The validator checks three sources:

CSV headers -- The column exists directly in the CSV file.
Federated mappings -- The field is mapped via federatedMappings in the config.
Conditional columns -- The field is set by a conditionalColumns entry with a matching toProperty.

Validation Rules by Entity Type¶

All Entity Types¶

These checks apply to every load, regardless of entity type:

Check	Error Message	Type
Config is not empty	`"Config is empty"`	Error
`loadType` is provided	`"loadType is required. At least one loadType must be specified."`	Error
`federatedId` is available (via CSV, mapping, or conditional)	`"federatedId is required. Must be present in csv headers, federatedMappings, or conditionalColumns."`	Error
`name` is available (via CSV, mapping, or conditional)	`"name is required. Must be present in csv headers, federatedMappings, or conditionalColumns."`	Error
If `federatedId` is in `federatedMappings`, the source column exists in CSV	`"federatedId is required..."`	Error
If `name` is in `federatedMappings`, the source column exists in CSV	`"name is required..."`	Error

Color (`COLOR`)¶

Check	Error Message	Type
`typePath` is available and set to `"color"`	`"typePath must be set to 'color' via csv data, conditionalColumn, or federatedMappings."`	Error
`loadType` contains `COLOR`	`"loadType must include COLOR."`	Error
Duplicate `federatedId` values in data	Per-row error with duplicate IDs	Error
Both hex and RGB columns present	`"hex and rgb(red, green, blue) values detected. hex will be ignored and rgb values will be used."`	Warning

Custom Entity (`CUSTOM_ENTITY`)¶

Check	Error Message	Type
`typePath` matches format `custom-entity:<subtype>`	`"typePath must be set to 'custom-entity:<subtypepath>' via csv data, conditionalColumn, or federatedMappings."`	Error
`loadType` contains `CUSTOM_ENTITY`	`"loadType must include CUSTOM_ENTITY."`	Error
Duplicate `federatedId` values in data	Per-row error with duplicate IDs	Error

Item (`ITEM`, `PROJECT_ITEM`, `ASSORTMENT`)¶

Items have the most extensive validation because of the family/option model.

Check	Error Message	Type
`loadType` contains only valid item types	`"loadType must be ITEM, PROJECT_ITEM, or ASSORTMENT."`	Error
`typePath` is `"item"` or `"item:<subtype>"`	`"typePath must be 'item' or start with 'item:' followed by a sub-type path."`	Error
`itemFamilyFederatedId` is available	`"federatedId is required..."` (checked as the federated ID key)	Error
Empty `itemFamilyFederatedId` values in rows	Per-row: `"itemFamilyFederatedId cannot be empty"`	Error
Conflicting family federated IDs (same name maps to different IDs)	`"The following families have conflicting federated IDs: ..."`	Error
Duplicate `itemOptionFederatedId` values	Per-row error with duplicate IDs	Error
`optionName` is available	`"optionName is not mapped. It won't be set if not present in csv, federatedMappings, or conditionalColumns."`	Warning
`itemOptionFederatedId` is available	`"itemOptionFederatedId is not mapped..."`	Warning

Item validation applies conditional column values

Before checking for empty or conflicting federated IDs, the item validator applies conditional column values to a copy of the data. This means if your itemFamilyFederatedId is computed via a conditional column, the validation will correctly use the computed values.

Common Error Messages Reference¶

Configuration Errors¶

Message	Cause	Fix
`"Config is empty"`	No configuration was provided to the LoaderProcess	Provide a valid config object with at least `loadType`
`"loadType is required..."`	The `loadType` array is missing or empty	Add a `loadType` array with at least one valid type
`"federatedId is required..."`	No `federatedId` column in CSV and no mapping/conditional for it	Add a `federatedId` column to CSV or configure it via `federatedMappings` or `conditionalColumns`
`"name is required..."`	No `name` column in CSV and no mapping/conditional for it	Add a `name` column to CSV or configure it via `federatedMappings` or `conditionalColumns`

Type Path Errors¶

Message	Cause	Fix
`"typePath must be set to 'color'..."`	Color load without a typePath of `"color"`	Add a conditional column: `{ "toProperty": "typePath", "default": "color" }`
`"typePath must be set to 'custom-entity:<subtypepath>'..."`	Custom entity load with invalid typePath format	Use format `custom-entity:yourSubtype` (e.g., `custom-entity:vendor`)
`"typePath must be 'item' or start with 'item:'..."`	Item load with invalid typePath	Use `item` or `item:subtype` format (e.g., `item:product:apparel`)

Data Integrity Errors¶

Message	Cause	Fix
`"itemFamilyFederatedId cannot be empty"`	A row has a blank `itemFamilyFederatedId`	Ensure every row has a value for the family federated ID column
`"The following families have conflicting federated IDs: ..."`	Same family name mapped to different family federated IDs	Ensure each family name consistently maps to the same federated ID across all rows
Duplicate federated ID errors	Multiple rows share the same option federated ID	Ensure each `itemOptionFederatedId` (or `federatedId` for colors/custom entities) is unique

Error and Warning Reporting¶

Issue Structure¶

Errors and warnings are structured as either row-level issues or general issues:

Row-level issues (specific to a CSV row):

{
  "rowNumber": 5,
  "columnIssues": [
    {
      "columnName": "itemFamilyFederatedId",
      "message": "itemFamilyFederatedId cannot be empty",
      "issueType": "CONFIG",
      "data": "{...row data...}"
    }
  ]
}

General issues (file or config-level):

{
  "message": "typePath must be set to 'color' via csv data, conditionalColumn, or federatedMappings.",
  "issueType": "CONFIG"
}

Issue Types¶

Issue Type	Description
`INVALID_DATA`	The data itself is malformed or invalid
`CONFIG`	A configuration issue (missing mapping, invalid loadType, etc.)
`SYSTEM_ERROR`	An internal system error during processing
`HEADER_MISMATCH`	CSV headers don't match expected properties
`VALIDATION_ERROR`	Data fails a validation check
`DUPLICATE_FEDERATED_ID`	Multiple rows have the same federated ID

Failure Areas¶

When a load fails, the failureArea on the LoaderProcess indicates where in the pipeline the failure occurred:

Failure Area	Meaning
`NONE`	No failure
`PARSING_CSV`	The CSV file could not be parsed (malformed, empty, etc.)
`VALIDATING_DATA`	Validation checks found errors in the config or data
`TRANSFORMING_DATA`	An error occurred during the preprocessing pipeline or entity construction

Accessing Error Details¶

Error and warning details for each preprocessing step are stored as JSON files attached to the LoaderProcess entity. You can access them by:

Admin Console: Navigate to the LoaderProcess entity and view its attached files.
API: Query the LoaderProcess entity and look at the preprocessingStepResults array, which contains file IDs for each step's results.
SDK: Fetch the LoaderProcess entity and iterate its preprocessingStepResults.

Each step result file is named loader-process-step-<Step Name>.json and contains the transformed rows along with any errors and warnings from that step.

Preprocessing Step Warnings¶

In addition to validation errors, the preprocessing pipeline itself generates warnings during execution:

Label/Slug Warnings (Steps 4 & 6)¶

Unrecognized columns: CSV columns that don't match any property slug or label on the entity type.
Archived properties: CSV columns that match a disabled or archived property. These columns are still processed but a warning is recorded.

Option Set Warnings (Steps 4 & 6)¶

Unrecognized option values: Values in Single Select or Multi Select columns that don't match any option in the corresponding option set.

Size Range Warnings (Entity Construction)¶

Missing template: A size range value references a template that doesn't exist.
Invalid sizes: Size values that aren't in the template's allowed sizes.
Unknown dimensions: For 2D size ranges, dimension names that aren't in the template.

Object Reference Warnings (Entity Construction)¶

Unresolved references: Object reference property values (federated IDs) that don't match any existing entity.