Salesforce Data Loader CSV Errors: Field Mapping, Lookups, and Validation

Data Loader finished. The success file has 800 rows. The error file has 200, each with an error message like "INVALID_FIELD_FOR_INSERT_UPDATE" or "FIELD_INTEGRITY_EXCEPTION: There's a problem with this country, even though it may appear correct." The CSV looked right. You ran the same kind of upload last quarter and it worked. What changed? Probably nothing about your data — Salesforce's validation surface is just deep enough that there's always something new to trip on.

Data Loader vs Data Import Wizard

Salesforce has two import tools, and they have different rules. The Data Import Wizard (in-browser) is friendlier but supports fewer objects (Accounts, Contacts, Leads, Solutions, and custom objects only) and is slower. Data Loader (desktop or CLI) supports every object and bulk operations but is stricter about CSV format. This guide focuses on Data Loader errors — the wizard's errors are usually a friendlier subset of the same set.

How Data Loader Validates Your CSV

Data Loader runs in sequence: parse the CSV, map columns to fields, validate each row against the object's schema (field types, picklist values, lookups), run org-level rules (validation rules, workflows, triggers), then commit or roll back. A row can fail at any stage, and the error file contains the message from the first failure it hit.

Where the error file lives

Data Loader writes a success file and an error file to the directory you specify in the operation. The error file contains every input row that failed, plus an ERROR column with the failure message. The success file contains the input rows plus a Salesforce ID column for inserts/upserts. Always set the directory explicitly — the defaults can be confusing across Data Loader versions.

Field Mapping Errors

Error: "INVALID_FIELD_FOR_INSERT_UPDATE"

You're trying to set a field that isn't writable. The usual culprits: standard read-only fields (Id on insert, CreatedDate, LastModifiedDate), formula fields, rollup summary fields, and fields you don't have field-level security access to. Drop these columns from the mapping or set Data Loader's "Use Bulk API" option to false (which gives slightly more permissive behavior).

Error: "INVALID_FIELD: No such column 'X' on entity 'Account'"

Your mapping file references a field name that doesn't exist on the object. Common causes: typo in the API name (custom field __c suffix missing), field was deleted from the org, you're connected to a sandbox where the field exists in production but not yet here, or wrong object (mapping refers to a field that exists on Contact but you're loading Accounts).

Lookup and Reference Errors

Salesforce uses 15- or 18-character record IDs for object references. When you import a Contact and set its AccountId, the AccountId column must contain valid Account IDs that already exist in the org. This is one of the highest-friction parts of importing related records.

Error: "INVALID_CROSS_REFERENCE_KEY"

The lookup value doesn't match an existing record. Either the ID is wrong, the referenced record was deleted, the referenced record is in a different org (sandbox vs production), or you're trying to use a 15-character ID where Data Loader expects 18 (or vice versa).

15 vs 18-character IDs

Salesforce IDs come in two forms: 15-character case-sensitive and 18-character case-insensitive. The 18-character form has a 3-character suffix that encodes the case of the first 15. Both forms reference the same record. Salesforce APIs and reports use 18-char by default; the UI sometimes displays 15-char. Mixing them in the same column is fine for Data Loader; using a 15-char ID with wrong casing fails.

Upsert by external ID

If your lookup target has an External ID field, you can reference it by external value instead of Salesforce ID. Set the column header to "Account.ExternalId__c:Lookup_External_Id__c" syntax, and Data Loader resolves the lookup at insert time. This is the cleanest approach when your source system has its own IDs and you want to avoid pre-pulling Salesforce IDs.

Picklist and Validation Errors

Error: "INVALID_OR_NULL_FOR_RESTRICTED_PICKLIST"

Picklist field with restricted values, and your CSV has a value that isn't in the picklist. Case matters. Trailing whitespace matters. Even values that look identical can mismatch (smart quote vs straight quote, em-dash vs hyphen). Compare your CSV values byte-by-byte against the picklist API names.

Error: "FIELD_CUSTOM_VALIDATION_EXCEPTION"

A custom validation rule fired. The error message includes the validation rule's error message. Look at the rule definition in Setup > Object Manager > [Object] > Validation Rules. Often the error message tells you exactly what's wrong (e.g., "Phone is required for new customers"), but sometimes you have to read the rule's formula to figure it out.

Record Type Errors

Error: "INVALID_RECORD_TYPE_ID"

If the object has multiple record types, you must specify which one each row uses. The RecordTypeId column expects the Salesforce ID of the record type. Common mistakes: leaving it blank (works only if there's a default record type for your profile), using the record type Name instead of ID, or using a record type ID from a different sandbox.

Get the record type IDs by running a SOQL query: SELECT Id, Name, DeveloperName FROM RecordType WHERE SObjectType = 'Account'. Copy the ID for each record type and use it in the import.

Owner ID Errors

Error: "INVALID_OWNER" or "OWNER_CANNOT_BE_SET"

OwnerId must be a User ID (15 or 18 chars) or a Queue ID. Common issues: user is deactivated, user doesn't have access to the record type, user is in a different role hierarchy that doesn't have edit access. If you're not sure who should own each record, leave OwnerId blank — Salesforce defaults to the running user (the user the Data Loader is authenticated as).

Date and Datetime Formatting

Salesforce stores datetimes in ISO 8601 with timezone offsets: 2026-05-15T14:32:05.000Z (UTC) or 2026-05-15T14:32:05.000-07:00 (with offset). Data Loader is lenient — it accepts many formats — but it converts everything to the running user's timezone before storing. If you import "05/15/2026" as a datetime field, Data Loader assumes midnight in the user's timezone, which may not be what you wanted.

Date fields vs datetime fields

Date fields hold just a date (no time, no timezone). Datetime fields hold both. Pushing a datetime into a date field truncates the time without warning. Pushing a date into a datetime field assumes midnight in the user's timezone. Know which type each field is before mapping.

Bulk API vs Serial Mode

Data Loader has two modes: Serial (one record at a time, slower, more permissive) and Bulk API (batches of up to 10,000 records, faster, stricter). Bulk API often fails on rows that Serial accepts — usually around concurrent edits, governor limits, or triggers that hit DML row limits. If a file fails in Bulk mode, retry the failed rows in Serial mode before debugging further.

Bulk API errors

Step-by-Step: Cleaning Your CSV

Step 1: Map every column to a field's API name

Don't map by label — map by API name. Custom fields end in __c. Standard fields use the standard API name (FirstName, not First Name). Drop columns that don't have a corresponding field.

Step 2: Resolve lookups before import

If you're importing related records, pull the parent IDs first (via SOQL or report) and join them into your CSV. Or use external-ID upsert to resolve at import time. Don't leave lookups blank hoping Data Loader will figure them out.

Step 3: Validate picklist values

For each picklist column, pull the current picklist values from Setup and compare to your CSV. Case-sensitive, trailing-whitespace-sensitive. Either map your values to the picklist or update the picklist to include your values.

Step 4: Strip read-only and computed fields

Remove columns for formula fields, rollup summaries, system audit fields (CreatedDate, LastModifiedDate), and any field you don't have FLS for. Keeping them mapped causes per-row failures.

Step 5: Run on 10 rows first

Always test on a small subset before running on the full file. Run 10 rows through Data Loader and check the error file. Fix issues. Re-run on a larger subset. Only run the full file once a small batch has succeeded end-to-end.

Best Practices for Big Imports

Prevention: Maintain a Mapping Template

Data Loader supports saving column mappings (.sdl files). Save mappings for each recurring import (Account upsert, Lead insert from event registrations, etc.) and reuse them. Combined with a CSV cleanup pipeline that runs before Data Loader, this turns recurring imports into a low-effort routine.