On this page
  1. How to read the error file
  2. Can’t log in
  3. Validation rule errors
  4. Duplicate rule blocks
  5. Insufficient access rights
  6. ID of incorrect type
  7. Malformed ID
  8. Required field missing
  9. Duplicate value
  10. Invalid email address
  11. Unable to lock row
  12. FAQ

Data Loader feels like magic right up until it stops cold. Suddenly you have an error file (an adventure in itself), a column of shouty capital letters, and no idea which field to fix.

This is the list I wish I’d had on my first migration: the ten errors that derail Data Loader imports most often, what each one actually means, and how to get unstuck. Search this page for the code in your error file and jump straight to the fix.

Prefer to read? Everything in the video is written out below.

Watch on YouTube ↗

First: how to read a Data Loader error file

Every failed row lands in the error file with an ERROR column at the end. It almost always follows the same pattern:

ERROR_CODE:Human-readable message:Field_API_Name --
  • The code tells you the category of problem. That’s what the sections below are organized by.
  • The message is often written by someone in your org (a validation rule, a duplicate rule), so it can say anything.
  • The field, when Salesforce includes it, tells you exactly which column to fix. When it’s blank, the problem is with the record as a whole, not one field.

Two habits that save hours: sort the error file by the ERROR column so identical failures group together, and fix one error type at a time before reloading.

Can’t log in to Data Loader (OAuth login failure)

This one is extra frustrating because it isn’t even about your data. You’re entering perfectly good credentials and Data Loader simply won’t connect.

What it looks like:

  • “Unable to complete OAuth login”
  • “Contact your Salesforce admin” (even when you are the admin)
  • “Failed to send request” or a destination/host URL error
Salesforce Data Loader OAuth login failure error

What it means: Data Loader is pointing at the wrong login door. It’s like having the right key and walking up to the wrong house. The tool is set up for one environment while your username belongs to another.

How to fix it:

  1. In Data Loader, open Settings and find the login/authentication host.
  2. Set it to login.salesforce.com for production or a Developer Edition org, or test.salesforce.com for a sandbox. If your org requires My Domain login, use your My Domain URL instead.
  3. Still stuck? Update Data Loader to the latest version (in Salesforce Setup, search Data Loader for the download), then try again.
  4. Last resort: uninstall and reinstall. Old login settings sometimes hang around.

FIELD_CUSTOM_VALIDATION_EXCEPTION

What it looks like:

FIELD_CUSTOM_VALIDATION_EXCEPTION:Clients must have a website:Website --
Salesforce validation rule error message during a Data Loader import

What it means: A validation rule in the target org rejected the row. The message is whatever text the admin who built the rule typed, which is why these errors sound so oddly specific. The field at the end (when there is one) is where the rule displays its error, and it’s usually the field you need to fix.

Read the message as a clue. If it describes a business requirement (“Clients must have a website”), it’s a validation rule. If it says “Use one of these records?”, skip to DUPLICATES_DETECTED.

How to find the rule: In Setup, go to Object Manager → [your object] → Validation Rules and look for the rule whose error message matches. Example: you loaded Accounts with Status = Client, your file had no Website column, and every client row failed.

Three ways to fix it:

  1. Fix the source data. The best outcome, because the records come in clean and valid. Avoid fake placeholder values like www.websitewebsite.com just to get past the rule. Future you will not thank you.
  2. Add a bypass for the migration user. A custom permission checked in the rule formula lets your load through without switching the rule off for everyone. Step by step: Salesforce Validation Rule Bypass for Data Migration.
  3. Deactivate the rule temporarily. It’s the fastest way to finish the load, but the records still don’t meet the rule, so the first person to edit one later gets blocked. Turning off many rules at once? How to Mass Deactivate Salesforce Flows and Validation Rules.

A consulting note: if you’re the one recommending option 2 or 3, make sure the bypass doesn’t become a permanent “old process forcing the new system” problem. Users shouldn’t have to fight the platform all day.

DUPLICATES_DETECTED

What it looks like:

DUPLICATES_DETECTED:Use one of these records?:--
Salesforce duplicate rule blocking a Data Loader insert

What it means: An active duplicate rule is set to Block, and the row matched an existing record. “Use one of these records?” is Salesforce’s default alert text, but admins can customize it, so if the message is unfamiliar, check the duplicate rules anyway.

How to fix it: Ideally you’d dedupe before loading. During a migration, though, you sometimes have to bring in records you know might be duplicates and merge them afterward. Your options:

  • In Setup → Duplicate Rules, change the rule’s action from Block to Allow (with an alert or report) for the duration of the load.
  • Or deactivate the rule temporarily and reload the failed rows.

Either way, put a reminder in your cutover plan to switch it back. Forgotten duplicate rules are how orgs end up with three Jane Smiths.

INSUFFICIENT_ACCESS_ON_CROSS_REFERENCE_ENTITY / INSUFFICIENT_ACCESS_OR_READONLY

This is the one that feels like Salesforce is playing hide-and-seek, because the message rarely tells you which field is the problem. It comes in two flavors.

INSUFFICIENT_ACCESS_OR_READONLY (insufficient access rights on object id): the running user can’t create or edit records on the object itself. Check the migration user’s object permissions (Create/Edit on Opportunity, for example) and field-level security on every field you’re loading.

INSUFFICIENT_ACCESS_ON_CROSS_REFERENCE_ENTITY (insufficient access rights on cross-reference id): the problem is a related record you’re pointing at, such as a lookup ID, record type, or owner, that the running user or the record owner can’t see. Example: loading Opportunities with a Contract ID when the owner has no access to that Contract.

A three-step way through it:

  1. Check the IDs in your file. Any ID Salesforce can’t find where it expects one can come back as an access error. Start with the high-yield columns: record type IDs, owner IDs, and the main parent lookup. Look for typos, IDs that shifted during a VLOOKUP, and columns mapped to the wrong field.
  2. Check whether the referenced record still exists. Copy an ID from the error file and paste it after your org’s URL (https://yourdomain.my.salesforce.com/ + the ID). If nothing opens, the record was deleted or the ID is wrong.
  3. Check sharing. If the record exists, log in as the record owner (Setup → Users → Login) and try to open it. If they can’t see it, Data Loader can’t link to it on their behalf either.

These steps cover most real-world cases, not every one. Salesforce returns this error for a lot of reasons.

Salesforce insufficient access rights error in Data Loader

FIELD_INTEGRITY_EXCEPTION: id value of incorrect type

What it looks like:

FIELD_INTEGRITY_EXCEPTION:Account ID: id value of incorrect type: 0035g00000AbCdE:AccountId --
Salesforce error: ID value of incorrect type

What it means: The ID is valid, it’s just the wrong kind of ID for that field. The classic cases:

  • A Contact ID in an Account lookup (the first three characters give it away: 001 is Account, 003 is Contact, 005 is User).
  • A record type name where Salesforce wants the record type ID.
  • A text value, like “Administration”, in a lookup column that needs an ID.

How to fix it: Check that each lookup column holds IDs from the right object, and that the column is mapped to the right field. Mapping two ID columns to each other’s fields is a very easy way to cause this one. When you need to look up IDs by legacy key instead of copying them around, see Salesforce External ID Fields.

MALFORMED_ID

What it looks like:

MALFORMED_ID:malformed id 001ABC:--

What it means: The value isn’t a Salesforce ID at all, usually because something mangled it on the way through Excel.

How to fix it:

  • IDs must be exactly 15 or 18 characters, with no spaces before or after.
  • Watch for Excel converting IDs to scientific notation or trimming them. Format ID columns as Text before pasting.
  • Watch for VLOOKUP matching the wrong record. 15-character IDs are case-sensitive, and Excel’s lookups aren’t, so 001...aBc and 001...Abc look identical to Excel. Use 18-character IDs for anything you’ll look up in a spreadsheet: How to Get the 18-Digit Salesforce ID.

REQUIRED_FIELD_MISSING

What it looks like:

REQUIRED_FIELD_MISSING:Required fields are missing: [LastName]:LastName --

What it means: A field that’s required at the field level is blank. Usually that’s Last Name on Contacts and Leads, Company on Leads, or a master-detail parent ID on a child record.

What it does not cover: fields marked required on the page layout. Page layouts only apply in the user interface, so Data Loader will happily load those as blank. If you need them filled, that’s a validation rule’s job (see FIELD_CUSTOM_VALIDATION_EXCEPTION).

How to fix it: The message lists the missing fields. Make sure each one has a column, the column is mapped, and no rows are blank. For master-detail children, load the parents first and map the parent’s ID or External ID.

DUPLICATE_VALUE

What it looks like:

DUPLICATE_VALUE:duplicate value found: Legacy_ID__c duplicates value on record with id: 001...:--

What it means: Not to be confused with DUPLICATES_DETECTED. This one isn’t a duplicate rule. It’s a field marked Unique (often an External ID) that already has that value on another record.

How to fix it:

  • If you meant to update the existing records, switch from Insert to Upsert and match on the External ID.
  • If the duplicates are inside your own file, dedupe the file first. Sort by the unique column and look for repeats.

INVALID_EMAIL_ADDRESS

What it looks like:

INVALID_EMAIL_ADDRESS:Email: invalid email address: jane.smith@@acme.com:Email --

What it means: Salesforce is strict about Email fields. A missing @, a double dot, or a stray space fails the whole row, not just the field.

How to fix it: Clean the column before loading: trim spaces, then filter for anything that doesn’t look like something@something.something. If a value can’t be saved, load it into a text field instead of losing it. The data is still useful, it just isn’t a valid email.

UNABLE_TO_LOCK_ROW

What it looks like:

UNABLE_TO_LOCK_ROW:unable to obtain exclusive access to this record or 1 records:--

What it means: Two batches tried to update the same record at the same time. It’s common when you load lots of children that share a parent (Contacts or Opportunities under the same Account), because saving a child briefly locks its parent.

How to fix it:

  • Sort your file by the parent ID so children of the same parent land in the same batch.
  • Lower the batch size in Data Loader settings (try 50, then lower).
  • If you’re using the Bulk API, turn on serial mode so batches run one at a time.
  • Automation on the parent makes locks worse. If Flows or triggers fire on every child insert, consider bypassing them during the load: How to Bypass Salesforce Flows During a Data Migration.

Frequently asked questions

How do I tell a validation rule error from a duplicate rule error?

Look at the code first: FIELD_CUSTOM_VALIDATION_EXCEPTION is a validation rule, DUPLICATES_DETECTED is a duplicate rule. Without the code, check the wording: validation errors describe a requirement (“Clients must have a website”), duplicate errors usually say “Use one of these records?”

What’s the fastest fix when I can’t log in to Data Loader?

Point Data Loader at the right login host: login.salesforce.com for production, test.salesforce.com for sandboxes. If that doesn’t work, update Data Loader to the latest version.

Why do I get insufficient access rights when my IDs look correct?

Because “correct” and “accessible” aren’t the same thing. The related record may have been deleted, or it exists but isn’t shared with the record owner or the running user. Check the ID resolves, then log in as the owner and try to open it.

Should I turn off validation rules and duplicate rules during a migration?

Sometimes, as long as you know the tradeoff and have a plan to turn them back on. A bypass for the migration user is usually safer than deactivating rules for everyone.

What’s the difference between DUPLICATE_VALUE and DUPLICATES_DETECTED?

DUPLICATE_VALUE means a field marked Unique already has that value. DUPLICATES_DETECTED means a duplicate rule matched the record. Different cause, different fix.

What does “id value of incorrect type” usually come down to?

An ID from the wrong object in a lookup, a record type name where the ID should be, or two ID columns mapped to each other’s fields.

Doing this for a whole org, not just one object?

One CSV is a tutorial. Forty objects, 15 years of history and a go-live date is a project. That’s the part I do for a living.

See how I run migrations →