The DUPLICATES_DETECTED error can happen during a data deployment if you're upserting or creating records.

Salesforce allows you to have Duplicate Rules that prevent you from accidentally adding the same records in twice. Common examples of this are for Accounts, Person Accounts, Contacts and Leads. These are typically useful to prevent duplicates values in your org, but can cause problems especially with deleted records that Salesforce will still think "exists" in the org even though you cannot access it.

If you try and insert a record that Salesforce thinks "exists" already on the org, it will return a DUPLICATES_DETECTED error with the IDs of the records it has problems with. Gearset will show an error like so:

A common example of this is during a restore from a backup. The above case is when I tried to restore a deleted Account record while I still had a Duplicate Rule enabled for Accounts.

You have a couple of options as to how you can resolve this:

First check to see if the record exists, on your org. If you are sure it has been deleted, you can disable the duplicate rules in your org. In Classic or Lightning:

1. Click Setup.
2. In the Quick Find box, enter Duplicate Rules or Matching Rules.
3. Review the rules to determine the criteria that might block the record creation.

Once you have disabled the rule, you should now be able to deploy the record.

You can then re-enable the rule once you have deployed the records.

Alternatively, for the data deployment, you could simply filter and exclude the record(s) that give rise to the error.

In general, however, it’s best to use a single field with a unique value to determine whether a record is created, updated or rejected as a duplicate. Here’s where external IDs come in useful. An external ID within Salesforce is a custom field that contains a unique identifier, e.g. a product code, a contract number or a social security number. You can set a unique record identifier (or 'upsert field') from the Salesforce UI by selecting the relevant checkbox when you create a new custom field:

If your records include external IDs, Gearset’s data loader can create or upsert your records based on this unique identifier in the target org. For more information, see our support article.