> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qwoty.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Error handling and validation

> Review and fix import errors before confirming, and download unimported rows after import.

## Pre-import validation

After uploading your file and mapping fields, Qwoty validates your data **before** importing. This lets you catch and fix errors without affecting your existing data.

## How it works

The 4-step import wizard surfaces errors at two points:

<Steps>
  <Step title="Upload">
    Drop your CSV file. Qwoty parses it and detects basic issues (file format, encoding, separator).
  </Step>

  <Step title="Mapping">
    Match each header to a Qwoty field. If a required field isn't mapped, you can't proceed to the next step.
  </Step>

  <Step title="Confirm">
    Qwoty validates every row against the rules of the target object. The summary shows:

    * The number of records that will be imported
    * The number of variants the file contains (for products)
    * The number of rows with **validation errors**

    Errors don't block valid rows. You can go back to fix your CSV or proceed.
  </Step>

  <Step title="Result">
    Qwoty processes the file. You see a count of rows imported and rows that failed. If any failed, click **Download unimported rows** to get a CSV of the failures with the reason for each.
  </Step>
</Steps>

## Error display

Errors are surfaced in two ways:

* **At the Confirm step** — a summary count tells you how many rows have validation errors before you commit
* **At the Result step** — after import, the **Download unimported rows** button gives you a CSV listing every failed row, the column at fault, and the validation message

The unimported-rows CSV is the same format as your original file, plus an `error_reason` column. Fix the rows in your spreadsheet and re-upload — only the failed rows are processed on the second import.

## Common error types

### Duplicate values

**Cause:** A unique field (like `product_api_name`) already exists in Qwoty or appears twice in your file.

**Fix:**

* Edit the duplicate value in your CSV and re-upload
* Remove one of the duplicate rows
* If you intended to update the existing record, populate the `id` column (the import detects updates automatically)

See [Uniqueness constraints](/user-guide/data-migration/reference/uniqueness-constraints) for the full list of unique fields.

### Invalid format

**Cause:** A value doesn't match the expected format — invalid UUID, wrong date format, lowercase enum where Qwoty expects capitalized values, percentage out of range.

**Fix:** Edit the cell to match the expected format. See [Field mapping](/user-guide/data-migration/reference/field-mapping) for the format requirements of each field type.

Common offenders:

* `pricing_model = flat` instead of `Flat` (case-sensitive)
* `settings[recurrence_type] = monthly` instead of `recurring`
* `default_vat = 20.0` instead of `FR_200`
* `amount = 99,00` instead of `99.00` (wrong decimal separator)
* `settings[is_active] = TRUE` instead of `true` (booleans must be lowercase)

### Missing required fields

**Cause:** A column marked with `*` in the Mapping step is empty for a given row.

**Fix:** Enter a value in the required field, or remove the row from your file.

### Relation not found

**Cause:** The referenced record doesn't exist — for example, a `parent_product_api_name` that points to a master that wasn't imported, or a `pricebook_id` referencing a pricebook that doesn't exist.

**Fix:**

* Import the parent records first (see [Import order](/user-guide/data-migration/reference/import-relations#import-order-rule))
* Or correct the reference value to match an existing record

### Inconsistent values within a master

**Cause:** Two variants of the same master declare different `settings[recurrence_type]`, different option names, or different shipping defaults.

**Fix:** Standardize the values across all variants of the same master. A master has a single recurrence type and a single set of option names — variants only differ on option **values**.

### Wrong file separator

**Cause:** Your CSV uses semicolon `;` instead of comma `,` (or vice versa). Qwoty expects comma.

**Fix:** Re-export your file with comma as the separator. In Excel, save as **CSV UTF-8 (Comma delimited)**.

## Tips for fewer errors

1. **Download the example file** from the import screen first — it shows the exact column headers and expected formats
2. **Clean your data** in your spreadsheet first — remove blank rows, fix typos, normalize enum values
3. **Import files in the correct order** — Master products → Products → Prices
4. **Test with small batches** before importing thousands of rows — fix the systematic issues, then run the full import
5. **Check for duplicates** before uploading — sort your file by the unique field
6. **Limit your file size** — split very large datasets into batches of a few thousand rows each, or use the [API](https://docs.qwoty.io)

## Related

<CardGroup cols={2}>
  <Card title="Field mapping" icon="arrow-right-arrow-left" href="/user-guide/data-migration/reference/field-mapping">
    Format requirements for every field type.
  </Card>

  <Card title="Uniqueness constraints" icon="fingerprint" href="/user-guide/data-migration/reference/uniqueness-constraints">
    Which fields are unique and how to use them.
  </Card>

  <Card title="Import relations" icon="link" href="/user-guide/data-migration/reference/import-relations">
    The right import order to avoid relation errors.
  </Card>

  <Card title="Prepare your CSV" icon="file-spreadsheet" href="/user-guide/data-migration/how-tos/prepare-csv-files">
    Step-by-step preparation guide.
  </Card>
</CardGroup>