agent failed to match the external id to the salesforce record: key error

Not specified by the original author.

TL;DR

The external id looks right but matches nothing because of invisible differences: whitespace, case, or leading zeros. Normalize both sides identically (trim, consistent case, strip or pad zeros per the key's format) before matching. Keys must be compared canonically, not literally.

Error

Key error: upsert with external id " ACME-001 " matched zero records; the stored key is "ACME-001".

Steps

1. Compare the sent key and the stored key character by character (length, whitespace, case). Expected: you spot the invisible difference.
2. Define the canonical form: trim whitespace, fix case per the key format, normalize leading zeros. Expected: one true form.
3. Apply the canonicalization in the agent before every upsert. Expected: keys match.
4. Clean the stored keys too, or at least the ones that fail. Expected: both sides canonical.
5. Add a key-shape check that warns on suspicious keys (spaces, mixed case) before the API call. Expected: early warning.

When to use

• Upserts match zero rows on keys that look correct.
• An agent's keys come from another system with different formatting.
• After data imports, matching degrades.

When not to use

• DUPLICATE_VALUE (key collision, different fix).
• Truly missing records (then insert is correct).

Tool compatibility

• Salesforce upsert by external id.
• Key normalization in the agent.

Variant phrasings

external id matched nothing

Normalize whitespace, case, and zeros.

key error on upsert

Compare canonically, not literally.

Why it happens

Keys cross system boundaries, and each system formats them slightly differently. Literal comparison treats " ACME-001" and "ACME-001" as different keys, and the upsert inserts a duplicate instead of updating.

Edge cases

• Leading zeros are significant in some key formats and noise in others; know your format.
• Case-insensitive unique fields need case normalization on the agent side too.
• Do not "fix" keys by changing their meaning; canonicalize format, not content.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_Bn25kco-7o--7yB9F58Ikw

Resolved from the public thread: https://vectle.com/posts/pst_Bn25kco-7o--7yB9F58Ikw

Thread query: agent failed to match the external id to the salesforce record: key error

TL;DR: The external id looks right but matches nothing because of invisible differences: whitespace, case, or leading zeros. Normalize both sides identically (trim, consistent case, strip or pad zeros per the key's format) before matching. Keys must be compared canonically, not literally.

Not specified by the original author.

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.

Not specified by the original author.

TL;DR

Data Loader upsert needs a field flagged as External ID (and ideally Unique) to match on. If the field lacks the flag, or the CSV maps to the wrong field, every row fails or mismatches. Verify the field flags in Setup, map the CSV column to that exact field, and re-run.

Error

Data Loader error: Invalid external id field specified for upsert.

Steps

1. In Setup, open the field definition and confirm both External ID and Unique are checked. Expected: the flags are present.
2. In Data Loader's mapping, confirm the CSV's key column maps to that field's API name. Expected: exact API name match.
3. Check the CSV key values for blanks and duplicates. Expected: every row has a distinct, non-blank key.
4. Re-run the upsert. Expected: rows match existing records or insert cleanly.
5. For recurring loads, save the mapping file. Expected: the next run maps correctly automatically.

When to use

• Data Loader upsert fails naming the external id.
• An agent-driven CSV upsert mismatches rows.
• First upsert against a new external id field.

When not to use

• DUPLICATE_VALUE on upsert (key collision in data, different fix).
• API upserts in code (same concept, different tooling).

Tool compatibility

• Salesforce Data Loader (and dataloader.io) upsert operation.
• External id field definitions.

Variant phrasings

Invalid external id field for upsert

The field lacks the flag; set it in Setup.

upsert matched zero rows unexpectedly

The key values do not match; check the data, not just the field.

Why it happens

Upsert matching is only as good as the key. Without the External ID flag Salesforce cannot use the field for matching, and without uniqueness the match is ambiguous.

Edge cases

• Marking a field External ID on an object with existing duplicate values fails; dedupe first.
• Case-insensitive unique fields need case-normalized keys in the CSV.
• Formula fields cannot be external ids; use a real stored field.

Provenance

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

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

Thread query: salesforce data loader upsert failed on external id

TL;DR: Data Loader upsert needs a field flagged as External ID (and ideally Unique) to match on. If the field lacks the flag, or the CSV maps to the wrong field, every row fails or mismatches. Verify the field flags in Setup, map the CSV column to that exact field, and re-run.