الانتقال إلى المحتوى الرئيسي

​
نظرة عامة

Import not working? This guide helps you identify and fix common import errors step by step.

​
How Import Validation Works

After uploading your file and mapping columns, Twenty validates your data:
  1. Validation runs — Twenty checks each row for errors
  2. Errors are highlighted — problematic rows appear in yellow
  3. You can fix in-place — edit cells directly in the import UI
  4. Or remove rows — skip problematic records entirely
Fix errors in the UI. You don’t need to go back to your spreadsheet. Edit cells directly during import to save time.

​
Step-by-Step Troubleshooting

​
Step 1: Identify the Error Type

Click on a highlighted row to see the specific error message. Common error types:
Error MessageWhat It Means
Duplicate values highlighted in yellowValue already exists in Twenty or appears twice in your file
{field} is not a valid {type} (hover on yellow cell)Data doesn’t match expected format
Required field highlightedA required field is empty
Can't connect to {object}. No unique record found... (import fails)Referenced record doesn’t exist
Too many records. Up to 10000 allowed (upload blocked)File has more than 10,000 records

​
Step 2: Fix the Error

Follow the specific instructions below for each error type.

​
Error: Duplicate Value

​
ما ستراه

Rows with duplicate values are highlighted in yellow in the import UI before the import starts.

​
What It Means

A unique field (email, domain) either:
  • Already exists in Twenty
  • Appears twice in your file

​
How to Fix

Option 1: Edit the duplicate value
  1. Click the cell with the error
  2. Change to a unique value
  3. Continue with import
Option 2: Remove the duplicate row
  1. Click the X next to the row
  2. The row will be skipped during import
Option 3: Let Twenty update the existing record
  1. Ensure your file includes a unique identifier (email, domain, or id)
  2. Map the unique identifier field
  3. Twenty will update the existing record instead of creating a duplicate
You can update unique fields too.
  • If you keep the id but change the email → the email will be updated
  • If you keep the email but change the id → the id will be updated
As long as one unique identifier matches, Twenty updates the record.

​
How to Prevent This Error

Before importing:
  1. Sort your spreadsheet by the unique field
  2. Remove duplicate rows
  3. Check if records already exist in Twenty
Soft-deleted records count toward uniqueness.Check Command Menu → See deleted records. Records there still enforce uniqueness. Permanently delete them or restore and update.
For more details: Uniqueness Constraints

​
Error: Invalid Format

​
ما ستراه

The cell value is highlighted in yellow. Hover over it to see the error message: 
{field name} is not a valid {field type}

​
What It Means

The data doesn’t match the expected format for that field type.

​
How to Fix — By Field Type

​
البريد الإلكتروني

Problem: Invalid email format Solution: Use format [email protected] 
❌ john.smith@
❌ john [email protected]
✓ [email protected]

​
النطاق

Problem: Inconsistent format may cause duplicates Solution: Use https://domain.com format (recommended) 
⚠️ acme.com         (valid, but not recommended)
⚠️ www.acme.com     (valid, but not recommended)
✅ https://acme.com  (recommended)
All formats are valid, but https://domain.com is recommended because it matches the format used by email/calendar sync. Using other formats may create duplicate companies.

​
تاريخ

Problem: Unrecognized date format Solution: Use consistent format throughout file 
✓ 2024-03-15        (YYYY-MM-DD - recommended)
✓ 03/15/2024        (MM/DD/YYYY)
✓ 15/03/2024        (DD/MM/YYYY)

​
هاتف

Problem: Missing required columns Solution: Include all phone columns
Columnمثال
Phones / Primary Phone Number4159095555
Phones / Primary Phone Country CodeUS
Phones / Primary Phone Calling Code+1

​
قيمة منطقية

Problem: Wrong boolean value Solution: Use uppercase TRUE or FALSE 
❌ true
❌ yes
❌ 1
✓ TRUE
✓ FALSE

​
Select / Multi-Select

Problem: Value doesn’t match existing options Solution: Use API names, not display labels How to find API names:
  1. Go to Settings → Data Model
  2. Select the object and field
  3. Enable Advanced mode (toggle at bottom right)
  4. Use the API name (e.g., OPTION_1, not “Option 1”)
❌ High Priority
✓ HIGH_PRIORITY

​
العملة

Problem: Missing amount or currency code Solution: Fill both columns
Columnمثال
Amount / Amount1234.56
Amount / CurrencyUSD

​
رقم

Problem: Non-numeric characters Solution: Numbers only, period for decimals 
❌ $1,234.56
❌ 1,234.56
✓ 1234.56
For complete format reference: Field Mapping

​
Error: Required Field Missing

​
ما ستراه

The row is highlighted in yellow with the required field cell marked.

​
What It Means

A required field is empty for this row.

​
How to Fix

Option 1: Enter a value
  1. Click the empty cell
  2. Enter a value
  3. Continue with import
Option 2: Remove the row
  1. If you don’t have the data, click X to skip the row

​
How to Prevent This Error

Before importing, identify required fields:
  1. Go to Settings → Data Model
  2. Select your object
  3. Check which fields are marked as required

​
Error: Relation Not Found

​
ما ستراه

This error appears after the import starts — the import fails with a message like: 
Can't connect to company. No unique record found with condition: id = 7776ee49-f608-4a77-8cc8-6fe96ae1e43f
This means there is no Company in Twenty with that specific identifier.
Unlike other errors, this one is not caught during the data review step. The import will start and then fail when it encounters the missing relation.

​
What It Means

You’re trying to link to a record that doesn’t exist in Twenty.

​
How to Fix

Option 1: Import parent records first
  1. Cancel the current import
  2. Import the parent records (e.g., Companies)
  3. Then import the child records (e.g., People)
Option 2: Fix the reference value
  1. Check the reference value in your file
  2. Ensure it exactly matches an existing record
  3. Verify format: domains should be https://domain.com
Option 3: Remove the relation
  1. Clear the cell to import without the relation
  2. Add the relation manually later

​
How to Prevent This Error

  1. Import in the correct order:
    • Companies first
    • People second (with company references)
    • Opportunities third
  2. Verify reference values:
    • Export parent records to get exact identifiers
    • Use domain format https://domain.com
    • Check for typos and case sensitivity
Import will fail if a reference is made to a non-existent record.Always import parent objects before child objects.
For more details: Import Relations

​
Error: File Too Large

​
ما ستراه

This error appears when uploading your file — the upload is blocked entirely: 
Too many records. Up to 10000 allowed
You won’t be able to proceed to the data review step until you reduce the file size.

​
What It Means

Your file has more than 10,000 records.

​
How to Fix

Option 1: Split into multiple files
  1. Divide your data into files of 10,000 records or fewer
  2. Import each file separately
  3. Maintain import order (Companies before People)
Option 2: Use API import For very large datasets, use the API which has no record limit. See: How to Import Data via API

​
Error: Field Not Recognized

​
What It Means

A column in your file can’t be mapped because the field doesn’t exist in Twenty.

​
How to Fix

  1. Go to Settings → Data Model
  2. Select the object you’re importing
  3. Click + Add field
  4. Create the custom field with the appropriate type
  5. Re-upload your file
The CSV import creates records, not fields. All fields must exist before importing.

​
Error: User Relation Empty

​
What It Means

You’re trying to assign a record to a user (Owner, Assignee) but the relation isn’t being mapped.

​
Common Causes

  1. User hasn’t accepted their invitation — the user doesn’t exist in Twenty yet
  2. Using user ID from old system — Twenty can’t match IDs from another system
  3. Wrong email format — the email doesn’t match the user’s Twenty account

​
How to Fix

  1. Ensure all users have accepted their invitation to your Twenty workspace
  2. Use the user’s email address (not their name or old system ID)
  3. Use the same email they used to join Twenty
Users must accept invitations before importing.If a user hasn’t accepted their invitation, records referencing them will have empty user relations.

​
Pre-Import Checklist

Avoid errors by checking these before importing:

​
File Requirements

File is CSV, XLSX, or XLS format
File has fewer than 10,000 records
File uses UTF-8 encoding

​
Data Quality

No duplicate emails (for People)
No duplicate domains (for Companies)
All dates use consistent format
All domains use https://domain.com format

​
Field Formats

Boolean fields use TRUE or FALSE (uppercase)
Select fields use API names, not display labels
Phone fields have all required columns
Currency fields have both Amount and Currency Code

​
العلاقات

Parent records imported before child records
Relation columns reference existing records
Domain format matches Twenty’s format exactly

​
نموذج البيانات

All custom fields exist in Settings → Data Model
Select options exist before importing

​
Still Having Issues?

If you’ve tried the above solutions:
  1. Download the sample file — see the exact format Twenty expects
  2. Export existing records — compare your file to working data
  3. Test with a small batch — try 5-10 rows first
  4. Check the reference articles: