Salesforce deploy "DUPLICATE_VALUE" in CI

By Kaveh Alemi·Latchkey

A component tried to create or set a value that must be unique, but that value already exists in the target org. Salesforce rejects the duplicate rather than overwriting, often on labels, API names, or unique fields.

What this error means

The deploy fails with "DUPLICATE_VALUE: duplicate value found: <field> duplicates value on record" for a specific component.

Deploy failed.
Type        Name        Problem
CustomField Account.Code__c  DUPLICATE_VALUE: duplicate value found: <unknown> duplicates value on record with id: <id>

Common causes

A unique value already exists in the target

The deploy adds a label, name, or unique field value that another record or component in the org already holds, so the uniqueness constraint fails.

A renamed component left the old one behind

Renaming in source without removing the old component can create two entities competing for the same unique value in the target.

How to fix it

Resolve the collision in the target org

1. Find the existing record or component holding the value named in the error.
2. Either reuse it, update the conflicting value, or remove the stale duplicate.
3. Re-run the deploy once the value is unique.

Use destructive changes for renames

When a rename creates a duplicate, include a destructiveChanges manifest so the obsolete component is removed in the same deploy.

sf project deploy start --target-org ci-org \
  --manifest manifest/package.xml \
  --post-destructive-changes manifest/destructiveChangesPost.xml

How to prevent it

• Keep unique field values and labels distinct across components.
• Pair renames with destructive changes so old entities are removed.
• Validate against a copy of the target before deploying.

Frequently asked questions

Related guides

References

• GitHub Actions documentation