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

.png)

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:
ENTITY_IS_DELETED: the record you referenced has been deletedMALFORMED_ID: "id value of incorrect type" or "bad id"MISSING_ARGUMENT: "Id not specified in an update call"INVALID_CROSS_REFERENCE_KEY: "invalid cross reference id"INSUFFICIENT_ACCESS_ON_CROSS_REFERENCE_ENTITY: "insufficient access rights on cross-reference id"FIELD_CUSTOM_VALIDATION_EXCEPTION: a validation rule blocked the recordREQUIRED_FIELD_MISSING: "Required fields are missing"DUPLICATES_DETECTED: "Use one of these records?"DUPLICATE_EXTERNAL_IDDUPLICATE_VALUE: a unique field already has this valueINVALID_OR_NULL_FOR_RESTRICTED_PICKLIST: the picklist value isn't allowedSTRING_TOO_LONG: "data value too large"INVALID_EMAIL_ADDRESS: Salesforce rejected an email valueUNABLE_TO_LOCK_ROW: another process had the record lockedCANNOT_EXECUTE_FLOW_TRIGGER and "the process failed" errorsThe meanings below come from Salesforce's API status code reference and Salesforce Help articles, linked where they apply.
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:
Name on Account.How to fix it before you rerun:
ENTITY_IS_DELETED: the record you referenced has been deletedWhat 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:
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:
.sdl file, or create the field in the target org.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:
003...) in an AccountId column.How to fix it before you rerun:
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:
Id column, often where a VLOOKUP found no match.Id column isn't mapped at all.How to fix it before you rerun:
Id column is mapped to the Id field.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:
OwnerId for an inactive user or a user who can't access the record.How to fix it before you rerun:
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:
RecordTypeId that isn't valid for the object, or isn't assigned to the loading user's profile or the new owner's profile.How to fix it before you rerun:
OwnerId in a separate update.INSUFFICIENT_ACCESS_OR_READONLY, means the user can't perform the action on the record itself. Check object permissions and sharing for that record.FIELD_CUSTOM_VALIDATION_EXCEPTION: a validation rule blocked the recordWhat 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:
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:
LastName on Contact or Name on Account.How to fix it before you rerun:
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:
allowSave=true. The default is false, so the save is blocked.How to fix it before you rerun:
DUPLICATE_EXTERNAL_IDWhat 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:
DUPLICATE_EXTERNAL_ID, clean up the duplicate values in the org and mark the external ID field as unique.DUPLICATE_VALUE: a unique field already has this valueWhat 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:
INVALID_OR_NULL_FOR_RESTRICTED_PICKLIST: the picklist value isn't allowedWhat 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:
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:
INVALID_EMAIL_ADDRESS: Salesforce rejected an email valueWhat 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:
UNABLE_TO_LOCK_ROW: another process had the record lockedWhat 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:
CANNOT_EXECUTE_FLOW_TRIGGER and "the process failed" errorsWhat 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:
Whatever the error, the same routine saves time:
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.
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.
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.