Fix Odoo CSV Import Errors: Common Failures and Solutions

The Problem

You prepared a CSV file with hundreds of records and clicked Import in Odoo, but it fails with cryptic error messages. CSV import issues are one of the top support requests because the error messages rarely tell you which row or cell caused the problem.

Common Error Messages

# Encoding errors:
UnicodeDecodeError: 'utf-8' codec can't decode byte 0xff in position 0

# Field mapping errors:
The following fields are not recognized: 'Product Name'
No matching record found for field 'Category' with value 'Electronics'

# Constraint violations:
IntegrityError: duplicate key value violates unique constraint
ValidationError: The operation cannot be completed: another record already has this reference

# Date format errors:
ValueError: time data '03/23/2026' does not match format '%Y-%m-%d'

Fixes for Each Error Type

1. Encoding Errors

The most common cause is saving CSV from Excel on Windows, which uses Windows-1252 or UTF-16 encoding instead of UTF-8.

Fix:

• In Excel: Save As > CSV UTF-8 (Comma delimited) — not plain "CSV"
• In LibreOffice: Save As > CSV > check "Edit filter settings" > select UTF-8
• Command line conversion: iconv -f WINDOWS-1252 -t UTF-8 input.csv > output.csv

2. Column Name Mismatch

Odoo expects either the technical field name or the exact label as column headers.

Fix: Use Odoo's export to get the correct column names:

1. Go to the list view of the model you want to import
2. Select a few records and click Export
3. Choose the fields you need
4. Export as CSV — use those exact column headers for your import file

# Common mappings:
# 'Name' or 'name' -> res.partner name field
# 'External ID' or 'id' -> for updates and references
# 'Customer/External ID' -> relational field reference
# 'Sales Price' or 'list_price' -> product price

3. Relational Fields (Many2one)

For fields that reference other records (like Category, Company, Salesperson), Odoo needs to find a matching record.

Error: No matching record found for field 'Category' with value 'Electronics'

Fix options:

• Use the exact name as it appears in Odoo (case-sensitive)
• Use External ID instead: column header category_id/id with value product.product_category_1
• Use the database ID: column header category_id/.id with the numeric ID
• Create missing records first, then import the main data

4. Date Format Issues

Odoo expects dates in YYYY-MM-DD format (e.g., 2026-03-23).

Fix: Convert your dates before import:

# In Excel, format the date column as:
# Custom format: YYYY-MM-DD

# Or use a formula:
=TEXT(A1, "YYYY-MM-DD")

# In Python:
import csv
from datetime import datetime
with open('input.csv') as f:
    reader = csv.DictReader(f)
    for row in reader:
        date = datetime.strptime(row['Date'], '%m/%d/%Y')
        row['Date'] = date.strftime('%Y-%m-%d')

5. Duplicate/Unique Constraint Violations

If a unique constraint exists (e.g., product reference, partner VAT), duplicates will fail.

Fix:

• Check for duplicates in your CSV before importing
• Use External IDs to update existing records instead of creating duplicates
• Remove duplicate rows from the CSV

# Check for duplicates in CSV:
import pandas as pd
df = pd.read_csv('data.csv')
duplicates = df[df.duplicated(subset=['Reference'], keep=False)]
print(duplicates)

6. Large File Timeouts

Importing thousands of records in one go can hit the HTTP timeout.

Fix:

• Split the CSV into batches of 500-1000 records
• Increase Odoo timeout: limit_time_real = 600 in odoo.conf
• Use the --batch-size parameter if importing via command line
• For very large imports (10K+), use a Python script with Odoo RPC

7. Boolean Fields

Odoo expects 1 or True for True, and 0 or False for False. Other values like "Yes", "No", "Y", "N" will fail.

8. Many2many Fields

To set multiple tags or categories:

# Column header: Tags or tag_ids
# Use comma-separated values in a single cell:
"Tag1,Tag2,Tag3"

# Or use External IDs:
# Column: tag_ids/id
# Value: module.tag_1,module.tag_2

Import Best Practices

1. Always do a test import with 5-10 records first
2. Use Odoo's export to get the correct column headers
3. Include External IDs (id column) for update capability
4. Use UTF-8 encoding
5. Use YYYY-MM-DD date format
6. Split large files into batches
7. Import parent/reference records first (categories, companies), then child records (products, contacts)
8. Back up your database before large imports

Debug Import Issues

# Enable import debug logging:
./odoo-bin --log-level=debug --log-handler=odoo.addons.base_import:DEBUG

# Check for encoding issues:
file -i data.csv  # shows detected encoding

# Validate CSV structure:
python3 -c "import csv; r=csv.reader(open('data.csv')); [print(i,len(row)) for i,row in enumerate(r) if len(row) != expected_cols]"