DUPLICATE_VALUE: duplicate value found" salesforce upsert

TL;DR

Upsert matched more than one record, or the external id value already belongs to another record: your key is not unique in practice. Query for every record carrying that external id value, fix the source data so the key is truly unique, and confirm the field is marked unique and external id.

Error

[ {
  "message" : "duplicate value found: External_Id__c duplicates value on record with id: 001...",
  "errorCode" : "DUPLICATE_VALUE",
  "fields" : [ "External_Id__c" ]
} ]

Steps

1. Query for all records with the colliding value: SELECT Id, Name FROM Account WHERE ExternalId_c = '[value]'. Expected: you see every record sharing the key.
2. Decide the survivor: usually the oldest or the one with the most activity. Expected: one canonical record per key value.
3. Fix the source data so each row carries a distinct external id; blank or placeholder ids shared across rows are the usual cause. Expected: no two rows share a key.
4. In Setup, confirm the field is marked both Unique and External ID. Expected: Salesforce enforces uniqueness going forward instead of failing at upsert time.
5. Re-run the upsert. Expected: each row updates its one matching record or inserts cleanly.

When to use

• Upsert fails with DUPLICATE_VALUE naming an external id field.
• A backfill upsert worked on a sample but fails on the full file (duplicate keys in the full data).
• The error names a record id different from the one you expected to update.

When not to use

• DUPLICATES_DETECTED (duplicate rule, not key collision).
• "required field missing" (absent data, not duplicate data).

Tool compatibility

• Salesforce REST, SOAP, and Bulk API upserts by external id.
• Data Loader upsert operation and agent upsert loops.

Variant phrasings

duplicate value found on record with id

The message names the existing record; open it to compare.

DUPLICATE_VALUE on standard fields

Email or other unique standard fields collide the same way.

Why it happens

Upsert is "update if exactly one match, insert if zero". Source data with blank keys, placeholder keys like "TBD", or real duplicates in the file breaks the exactly-one assumption.

Edge cases

• Case-insensitive unique fields treat "ABC" and "abc" as the same; normalize case in the source.
• Leading and trailing whitespace makes two keys look different to humans but identical to Salesforce; trim in the source.
• Merging two records that share an external id needs the survivor chosen first, or the merge itself throws.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_TxTYV9WDMNWMBz6nXlMpBQ

Resolved from the public thread: https://vectle.com/posts/pst_TxTYV9WDMNWMBz6nXlMpBQ

Thread query: "DUPLICATE_VALUE: duplicate value found" salesforce upsert

TL;DR: Upsert matched more than one record, or the external id value already belongs to another record: your key is not unique in practice. Query for every record carrying that external id value, fix the source data so the key is truly unique, and confirm the field is marked unique and external id.