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

# Import troubleshooting

> Solve common data import issues

This guide helps you diagnose and resolve common import problems.

## Common errors and solutions

### Missing required columns

**Error:** `Required column 'productSku' is not mapped`

**Cause:** Your file doesn't have a column mapped to a required field.

**Solution:**

1. Check that your file has a column containing product SKUs
2. The column might have a different name (e.g., "Part Number", "Item Code")
3. In the mapping step, manually map your column to `productSku`

<Info>
  Required columns vary by import type. For BOM imports, `productSku` and `quantity` are always required.
</Info>

### Invalid unit codes

**Error:** `Unknown unit 'kilogrammes'`

**Cause:** Your unit values don't match Variable's standard units.

**Solution:**

1. In the value mapping step, map your unit to a standard Variable unit
2. Common mappings:
   * `kilogrammes` to `kg`
   * `pieces` or `units` to `pcs`
   * `square meters` to `m2`

### Date format issues

**Error:** `Invalid date format in column 'startDate'`

**Cause:** Variable couldn't parse your date values, or the **Date format** dropdown doesn't match the format in your file.

**Solution:**

1. On the column-mapping screen, set the **Date format** dropdown to match your file (Day / Month / Year, Month / Day / Year, Year / Month / Day, Year Month, Month Year, or ISO 8601).
2. Make sure every row in the same date column uses the same format - mixed formats in one column will fail.
3. See [Date format](/docs/import/upload-map-columns#date-format) for the full list of accepted variations within each option.

<Warning>
  Mixing date formats in the same column will cause parsing errors. Clean your data so every value in the column uses the same format before importing.
</Warning>

### Decimal separator problems

**Error:** Quantities appear wrong (e.g., `1234` instead of `1.234`)

**Cause:** Wrong decimal separator selected.

**Solution:**

1. Check your file's number format:
   * US/UK: `1,234.56` (comma for thousands, period for decimals)
   * European: `1.234,56` (period for thousands, comma for decimals)
2. Select the correct decimal separator in the import settings

### Empty or whitespace-only values

**Error:** `Required value missing in row 47`

**Cause:** A required field has empty or whitespace-only values.

**Solution:**

1. Check your source file for empty cells in required columns
2. Remove or fill in missing values before re-importing
3. Consider whether the row should be included at all

## Duplicate handling (idempotency)

Variable is designed to handle re-imports safely. Understanding how deduplication works helps avoid unexpected results.

### Product deduplication

Products are matched by SKU within your company:

* Same SKU = same product (reused, not duplicated)
* Different SKU = different product (new one created)

<Note>
  By default, re-imports reuse a matched product without overwriting it. For **material and product imports** you can change this with the [import match mode](/docs/import/import-behavior#import-match-mode-products-and-materials) on the upload screen - **Overwrite existing** or **Fill missing only** update scalar fields on matches (relationships stay untouched). BOM imports always reuse existing products. Otherwise, to land fixes from your source file, edit the items directly in the app or via the API.
</Note>

### Input deduplication

Inputs are only added to products when:

* The product was **created during this import**, OR
* The product has type **UNKNOWN**, OR
* The product has **no existing inputs**

**Why is my product not getting new inputs?**

If a product is already LIVE with inputs, it's considered "fully modeled" and won't receive additional inputs from re-imports.

**Solution:**

1. Change the product to UNKNOWN before re-importing
2. Or add inputs manually through the UI
3. Or create inputs via the API

<Note>
  This behavior prevents accidental duplication when re-running imports. It's a safety feature, not a bug.
</Note>

### Detecting duplicates within a file

Variable detects duplicate inputs by comparing:

* Source product/material ID
* Quantity
* Unit code

Duplicates within the same import are automatically deduplicated.

## Large file tips

### Performance optimization

For imports with 10,000+ rows:

1. **Clean your data first**
   * Remove empty rows
   * Remove summary/total rows
   * Ensure consistent formatting

2. **Split by product**
   * Import each top-level product separately
   * Easier to track and troubleshoot

3. **Monitor progress**
   * Large imports process in batches (250-1,000 items)
   * You can navigate away - you'll be notified when complete

<Info>
  Import progress is tracked in the background. Check the import detail page for status updates.
</Info>

## Import status reference

| Status     | Description              | Action                              |
| :--------- | :----------------------- | :---------------------------------- |
| created    | Import record created    | Upload a file                       |
| uploaded   | File received and parsed | Configure mappings                  |
| processing | Import in progress       | Wait for completion                 |
| done       | Import completed         | Review results                      |
| error      | Import failed            | Check error message, fix, and retry |
| stopped    | Import cancelled         | Re-start if needed                  |

### Recovering from errors

When an import fails:

1. **Check the error message** - Usually indicates the specific problem
2. **Review your data** - Look for the row or column mentioned
3. **Fix the source file** - Correct the issue in your original file
4. **Re-upload** - Create a new import with the corrected file

<Warning>
  Failed imports may have partially created data. Check for any products or materials created before the failure.
</Warning>

## File format issues

### CSV parsing problems

**Symptoms:** Columns misaligned, data in wrong fields

**Common causes:**

* Commas in data values (not quoted)
* Inconsistent quoting
* Wrong delimiter (semicolon vs comma)

**Solutions:**

1. Ensure values with commas are quoted: `"Saddle, leather"`
2. Use consistent quoting throughout
3. Check your regional CSV settings

### XLSX parsing problems

**Symptoms:** Data missing or incorrect

**Common causes:**

* Wrong sheet selected (multi-sheet workbooks default to the first sheet)
* Merged cells
* Hidden rows or columns
* Formulas instead of values

**Solutions:**

1. On upload, use the **Select sheet to import** dropdown to pick the correct sheet
2. Unmerge cells
3. Unhide rows and columns
4. Copy and paste as values to resolve formulas

## Getting help

If you're still experiencing issues:

1. **Check the error details** - Expand the error message for more information
2. **Export your mappings** - Useful for support debugging
3. **Contact support** - Include the import URL and error message

<Note>
  When contacting support, include:

  * The import URL (from your browser's address bar)
  * The error message
  * A sample of the problematic data (anonymized if needed)
</Note>

## Related guides

* [Preparing your BOM file](/docs/import/prepare-bom) - Data format requirements
* [Uploading and mapping columns](/docs/import/upload-map-columns) - Mapping configuration
* [What happens after upload](/docs/import/import-materials) - Understanding the import process