How to fix DUPLICATE_VALUE in Salesforce deployments

A record or metadata component being created already has a matching unique value or Developer Name in the target org.

Surfaces during: both runtime DML inserts and metadata deploy validation

What it means

DUPLICATE_VALUE means Salesforce rejected an insert or a new metadata component because something about it, a unique field value, an external ID, or a Developer Name, already exists in the target org. Salesforce enforces uniqueness at the platform level and will not silently overwrite the existing record or component.

It's a broader catch-all than DUPLICATE_DEVELOPER_NAME or DUPLICATE_EXTERNAL_ID; those are the two most common specific flavors, but this code can also fire on any custom field with the Unique attribute set.

Diagnosis

Common causes

Unique field already populated

A field marked unique or an external ID already has a matching value in the target org from an earlier load or deployment.

Parallel work created the same Developer Name

Two developers independently created a component, a custom field, record type, or permission set, with the same Developer Name in separate branches.

Duplicate rules blocking test data

A duplicate or matching rule in the target org flags Apex test data as a duplicate of an existing record.

The fix

Upsert instead of insert
Use upsert with the correct external ID field so existing records are updated rather than re-created.
Rename the colliding component
Give the newer metadata component a unique Developer Name and update any references to it.
Review duplicate rules for test context
Confirm duplicate and matching rules do not block the specific record shapes your Apex tests insert.

In practice

How Serpent prevents this

Serpent AI flags overlapping Developer Names across concurrent tasks before either one reaches a deploy, so the collision is caught during scoping. See the Salesforce deployment error library.

Metadata and data in one deployment flow in Serpent

Prevention

Default to upsert over insert wherever an external ID exists

Use upsert as the standard pattern for any object with a stable external key, so a re-run of a load never collides with itself.

Bypass duplicate rules deliberately in test setup, not by accident

Set DMLOptions.DuplicateRuleHeader.allowSave explicitly in test data factories that need to insert records duplicate rules would otherwise flag.

Agree on naming conventions before parallel feature work starts

Settle Developer Name prefixes per team or feature at kickoff, not after the first collision reaches a shared org.

Common questions

DUPLICATE_VALUE, answered

Can I just delete the existing record and redeploy?

Only if it is genuinely obsolete. Check what depends on it first, since deleting the wrong duplicate can break other metadata that references it.

Does DUPLICATE_VALUE only apply to custom fields, or standard ones too?

It applies to both. Standard unique fields, like a Contact's Email in some org configurations, enforce the same constraint as a custom field with Unique checked.

Is DUPLICATE_VALUE the same as a Salesforce duplicate-management rule warning?

No. Duplicate and matching rules in Setup are a softer, configurable warning or block on likely-duplicate records; DUPLICATE_VALUE is a hard platform-level uniqueness constraint that can't be overridden by the user in the UI.

Start free. No credit card, no install, no commitment.

Set up in under 15 minutes. No DevOps hire needed.

Start free Book a demo