The External ID used for upsert is missing or not unique.

Problem Explanation

Upsert relies on External IDs to decide whether to insert or update a record. If Salesforce can’t match one record exactly, it inserts a new one.

Root Cause(s)

1. External ID field not marked correctly

2. Null external ID value in request

3. Duplicate external ID values

Step-by-Step Solution

1. Mark field as External ID + Unique

2. Validate payload includes external ID

3. Clean existing duplicate records

Edge Cases & Variations

1. Case sensitivity matters for text external IDs

2. Bulk API handles failures differently

Common Mistakes to Avoid

1. Using Name field as External ID

2. Skipping uniqueness constraint