'duplicate value found: unknown' on a Salesforce deploy

What does "duplicate value found: unknown" mean?

Two things have the same value where Salesforce wants them to be unique, and the message cannot tell you which. Both IDs print as <unknown>. The best write-up is on Stack Exchange (Salesforce Stack Exchange). It splits the error into two cases: a deployment error, and a DML error from code or a data load.

For a data load or Apex insert, the cause is a field with a unique constraint. For a metadata deploy, it is harder, and the next section is for that.

How do I find the guilty component?

The file and position are in the line. A typical one looks like this:

Error: objects/Opportunity.object(2098,13): duplicate value found: <unknown> duplicates value on record with id: <unknown>

The numbers in brackets are line 2098, column 13 of the Opportunity.object file. Open the file at that line. In the accepted answer's case it was the StageName picklist.

If you have no line number, cut the package down until it fails with only one component in it. Then remove parts of that component until it passes. Slow, but it finds the component.

What causes it?

• A picklist value that already exists in the target as inactive. The answer says to check whether the target holds an inactive value with the same name as one you are deploying. If so, delete that value in the target, and the deploy goes through (Salesforce Stack Exchange).
• Field history tracking on the object. For problems that are not about picklists, the same answer says odd behavior often shows up when field history tracking is on, and it links to threads on workarounds, including this one.
• Repeated entries in your own file. If you merged two files by hand, a value may appear twice. This one is easy to see. Salesforce prints a clearer message for it: a picklist with Red listed twice returns Duplicate picklist value red.

How do I fix it in Setup?

1. Open the target org. Go to Setup, Object Manager, the object, Fields and Relationships, and the field named at the line you found.
2. For a picklist, look at the Inactive Values list. Delete any value that matches one you are deploying, or reactivate it so the deploy updates it.
3. If the picklist is clean and history tracking is on, the linked threads suggest switching tracking off for the deploy. Note which fields are tracked first.
4. Validate again.

How do I fix it with the CLI?

Narrow it to the one component first:

sf project deploy start --metadata CustomField:Opportunity.StageName --dry-run --test-level NoTestRun -o target-org

Standard picklists such as StageName may need the standard value set instead of the field. If the check passes, widen the package again, one piece at a time.

How do I prevent it?

Compare picklist values between the two orgs before the release, and delete stale inactive values from the target. The custom field entry covers picklist basics, and the change set errors guide has the other message you will see on picklists, where target-only values go inactive. AI Salesforce deployments shows a component-level diff of the two orgs before you commit a bundle.