Salesforce Data Load Errors: What They Mean and How to Fix Them

Sam Hoult
November 2, 2026

When a Salesforce data load fails, each failed row comes back with a status code such as ENTITY_IS_DELETED or FIELD_CUSTOM_VALIDATION_EXCEPTION and a message. The code tells you which kind of problem it is: a bad or missing ID, a record you can't access, a rule in your org, or a value the field won't take. Find your error below, fix the rows in the source file or the setting in the org, then rerun only the failed records.

Jump to your error:

The meanings below come from Salesforce's API status code reference and Salesforce Help articles, linked where they apply.

1. "An error occurred while trying to update the record. Please try again."

What it means. This is a generic wrapper message. Salesforce returns it when a record save fails in Lightning, for example from a Lightning component, and the real reason sits underneath it. In Salesforce's own example of this error, the underlying field error is REQUIRED_FIELD_MISSING.

Common causes:

How to fix it before you rerun:

2. ENTITY_IS_DELETED: the record you referenced has been deleted

What it means. Salesforce's description is "You can't reference an object that has been deleted." The row points at a record ID, either as the record to update or in a lookup, and that record is in the Recycle Bin or gone for good.

Common causes:

How to fix it before you rerun:

3. "Field mapping is invalid": Data Loader can't find a mapped field

What it means. This message comes from Data Loader, usually the command-line version that uses a saved .sdl mapping file. Before it loads anything, Data Loader checks that every Salesforce field in the mapping exists on the object for the user who is logged in. If one doesn't, it stops with "Field mapping is invalid" followed by the column and field name. You can see this check in Data Loader's open-source code.

Common causes:

How to fix it before you rerun:

4. MALFORMED_ID: "id value of incorrect type" or "bad id"

What it means. A value in an ID or lookup column isn't a valid Salesforce ID for that field. Salesforce's Data Loader ID article lists "MALFORMED_ID: Object name id: id value of incorrect type" for inserts and updates and "MALFORMED_ID: bad id" for deletes.

Common causes:

How to fix it before you rerun:

5. MISSING_ARGUMENT: "Id not specified in an update call"

What it means. An update or delete row has no record ID. Salesforce lists this error in the same Data Loader ID article.

Common causes:

How to fix it before you rerun:

6. INVALID_CROSS_REFERENCE_KEY: "invalid cross reference id"

What it means. Salesforce's description is "An invalid foreign key can't be set on a field." In practice the row sets a lookup, owner or record ID to a value that doesn't match a record in this org.

Common causes:

How to fix it before you rerun:

7. INSUFFICIENT_ACCESS_ON_CROSS_REFERENCE_ENTITY: "insufficient access rights on cross-reference id"

What it means. The record you're saving refers to another record, through a lookup, master-detail field, owner or record type, and the user running the load can't access that other record. Salesforce explains the scenarios in this Help article.

Common causes:

How to fix it before you rerun:

8. FIELD_CUSTOM_VALIDATION_EXCEPTION: a validation rule blocked the record

What it means. A custom validation rule in your org returned true for the row, so Salesforce rejected it with the rule's own error message. Salesforce's Help article on this error in Outlook Integration shows the same pattern: a validation rule blocking an update. Validation rules apply to records created and updated through the API, even when the fields they check aren't in your file.

Common causes:

How to fix it before you rerun:

9. REQUIRED_FIELD_MISSING: "Required fields are missing"

What it means. Salesforce's description is "A call requires a field that wasn't specified." The message lists the missing fields, for example "Required fields are missing: [Name]".

Common causes:

How to fix it before you rerun:

10. DUPLICATES_DETECTED: "Use one of these records?"

What it means. A duplicate rule matched the record against one that already exists, and Salesforce blocked the save. Salesforce shows "Use one of these records?" as the message.

Common causes:

How to fix it before you rerun:

11. "Duplicate id specified" and DUPLICATE_EXTERNAL_ID

What it means. Two rows in the same batch point at the same record. Salesforce's Help article shows the message as "Duplicate id specified: 0013000000auCyTAAU". The related DUPLICATE_EXTERNAL_ID code means an external ID in your upsert matches more than one existing record.

Common causes:

How to fix it before you rerun:

12. DUPLICATE_VALUE: a unique field already has this value

What it means. Salesforce's description is "You can't supply a duplicate value for a field that must be unique." A field marked unique, often an external ID, already holds that value on another record.

Common causes:

How to fix it before you rerun:

13. INVALID_OR_NULL_FOR_RESTRICTED_PICKLIST: the picklist value isn't allowed

What it means. The value isn't in the field's value set, or isn't available for the record type, and the picklist is restricted. Salesforce covers both cases in this Help article.

Common causes:

How to fix it before you rerun:

14. STRING_TOO_LONG: "data value too large"

What it means. Salesforce's description is "The specified string exceeds the maximum allowed length." The message names the field and its maximum length, in the form "data value too large: ... (max length=...)".

Common causes:

How to fix it before you rerun:

15. INVALID_EMAIL_ADDRESS: Salesforce rejected an email value

What it means. Salesforce's description is "A specified email address is invalid." The value in an Email field isn't in a format Salesforce accepts.

Common causes:

How to fix it before you rerun:

16. UNABLE_TO_LOCK_ROW: another process had the record locked

What it means. Salesforce locks a record while it's being changed, and a transaction waits up to 10 seconds for a lock before it times out. Updating a child record also locks its parent. Salesforce explains this in its row lock article.

Common causes:

How to fix it before you rerun:

17. CANNOT_EXECUTE_FLOW_TRIGGER and "the process failed" errors

What it means. Salesforce's description of CANNOT_EXECUTE_FLOW_TRIGGER is "The flow trigger or the flow failed to execute." Your load saved the record, a record-triggered flow or process ran, and that automation failed, so the whole save was rolled back. In the UI and in older orgs you may see it as "We can't save this record because the ... process failed" with the name of the process.

Common causes:

How to fix it before you rerun:

18. Before you rerun a failed load

Whatever the error, the same routine saves time:

  1. Keep the error file. Group the failures by status code and fix the biggest group first.
  2. Fix the cause in the source file or the org. Editing the error file by hand makes the next run harder to repeat.
  3. Rerun only the failed rows. Rerunning the whole file can create duplicates of the rows that already succeeded.
  4. Undo a run that went wrong. If the successful rows are the problem, see how to roll back a failed Salesforce import. Dataimporter's Rollback deletes the records an insert job created, for up to 7 days after the job.

Dataimporter is a Salesforce data loader that lets you test on a sample, look up related records by any text, email or phone field instead of raw IDs, retry failed records and roll back inserts. You can try it for free.

19. Summary

Most failed loads come down to a few causes: IDs that don't match a record in this org, records the loading user can't see, rules and automation in the org, and values a field won't accept. Read the status code, fix the cause at the source, test on a sample and rerun only the failures. For the steps around the load itself, see our Salesforce data migration checklist.

Frequently asked questions

Where do I find the error for each failed row?

Data Loader writes an error file for each run, containing the rejected records with a column that describes why each one failed. Most other tools, including Dataimporter, list the failed records and their error messages for each job run. Start there before you change anything.

What does "An error occurred while trying to update the record" mean?

It's a generic message that wraps the real error. Look at the detail underneath it for a status code such as REQUIRED_FIELD_MISSING or DUPLICATES_DETECTED, then fix that cause.

Why does an ID work in Salesforce but fail in my file?

Usually because the file has a 15-digit ID that changed case in Excel, an ID from another org, or an ID of the wrong object type. Use 18-digit IDs and check they come from the org you're loading into.

Can I turn off validation rules and flows for a data load?

Yes. You can add a bypass condition for the loading user, or deactivate the rules and flows for the load and reactivate them afterwards. Turning them off by hand is easy to forget, so record what you changed. Dataimporter's Automation Control, on Enterprise plans, does the switching around the job for you.

Should I rerun the whole file after fixing errors?

No. Rerun only the rows that failed. The rows that succeeded are already in Salesforce, and loading them again as inserts creates duplicates.

Get Started with Dataimporter