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.
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.
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 errors. 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.