Skip to main content
All CollectionsTroubleshootingData seeding / restoration
Resolving data deployment errors: DUPLICATE_VALUE & DUPLICATE_EXTERNAL_ID
Resolving data deployment errors: DUPLICATE_VALUE & DUPLICATE_EXTERNAL_ID

This article explains when and why the DUPLICATE_VALUE and DUPLICATE_EXTERNAL_ID errors occur, and how to fix them

Tom Smith avatar
Written by Tom Smith
Updated over a week ago

The DUPLICATE_VALUE and DUPLICATE_EXTERNAL_ID errors can happen during a data deployment if you're upserting records.

What causes the error?

When upserting, Gearset tells Salesforce to use an external ID field to match records between the source and target. If multiple records have the same value for the external ID field, Salesforce will throw an error during the upsert.

The DUPLICATE_VALUE error means that one or more records being deployed from the source have the same value for the external ID field. Salesforce doesn't know which record to use for the upsert, so throws an error.

The DUPLICATE_EXTERNAL_ID error means that one or more records in the target have the same value for the external ID field. Salesforce doesn't know which record to upsert, so throws an error.

How do I fix the error?

There are a few ways to avoid this error.

Use a different external ID for upserting

Ideally you would have an external ID that doesn't allow duplicates.

Using this external ID field for the upsert means that there won't be duplicates, so we won't hit these errors.

You might also have a Duplicate Rule against an external ID field to the same effect.

Note: When using a combination of External ID’s to match records for upserting, these will be added as AND - meaning that it will have to use a combination of all of them in order to cross-reference, and therefore upsert. If one of them doesn’t match, this means it will “create” rather than “upserting” the record. If that happens, when Gearset tries to create a new record it will hit a DUPLICATE_VALUE error because some of the fields might match (even if not all). If you selected multiple External IDs simultaneously and hit this error, check in your orgs if you're missing a match in any of the selected fields or remove one of them from the configuration.

Create new records instead of upserting

Creating new records instead of upserting existing records will avoid these errors.

If you have a Duplicate Rule in the target, you may run into a different error. Deactivating the Duplicate Rule during the deployment will help avoid this.

Exclude the records causing errors from the deployment

It may be a few records causing the errors. You can use Gearset's data deployment filters to exclude these records from your deployment.

Once you've successfully deployed the rest of the data, you can try using a different external ID to upsert the remaining records.

Did this answer your question?