Error overview
You may run into this Salesforce validation error when deploying a new or changed DuplicateRule metadata item, or when deploying new rules added to an existing duplicate rule.
An example of the error message in our app would be:
"SortOrder must be in sequential order from 1."
Explanation of the error
This validation error happens because Salesforce enforces a strict sequence (e.g. 1, 2, 3... etc) for Duplicate Rules in the target org.
If there are multiple Duplicate Rules with the same <sortOder> value specified within the XML file, Salesforce will restrict your change and prevent it from deploying.
Resolution
Is sortOrder not reflecting correctly on the XML file?
If <sortOrder> values are not reflecting correctly in the XML file of your Duplicate Rule on your comparison results, do the following:
In your Salesforce org navigate to Setup > Home > Duplicate Rules > expand View and select the object your Duplicate Rule belongs to.
You can then manually edit the sequence of Duplicate Rules in your source org using the arrows in the "Order" column.
An example of an incorrect sortOrder in the source org (where sortOrder values are: 1, 2, 1 instead of 1, 2, 3).
Deploying changes via a PR opened in your Gearset Pipeline?
If your deploying from a Git branch (e.g. feature branch when using Gearset Pipelines), you'd need to re-order the Duplicate Rules in the source org and re-commit the changes to your feature branch.
Alternatively, you may consider making changes directly in your feature branch in the Git provider.
Workaround 2: Lower the API version for org to org validations
Note: This workaround applies only when the sequence of sortOrder values of your Duplicate Rule is correct (e.g. 1, 2, 3... etc).
Based on troubleshooting done with Gearset users, we found that when the sortOrder of the rules for a given Duplicate rule item is reflecting correctly in the XML file, the workaround that help the validation to succeed was:
If you're running your validation on the currently newest version of the Metadata API (e.g. API v65), try lowering the API version to API v64 (see our documentation for guidance on amending API version in your comparison).
Context: on below example (see screenshot) user run into this error when API v64 was the newest version supported, so in that use case lowering the API version in Gearset to API v63 helped to resolve the error.
Common scenarios that can lead to this error
Below we're providing more guidance on two most common scenarios that can lead to this validation error, along with suggestions on how to approach troubleshooting and fixing the issue.
Scenario 1
When you try to deploy a Duplicate Rule with a sortOrder that creates a gap in the target org's list of rules, or if you deploy a subset of rules that conflicts with the target org's existing order.
Solution
The safest fix is to retrieve all duplicate rules for that object from the source org and deploy them together. This resets the order in the target org to match the source exactly. When you deploy the full set, Salesforce overwrites the target's ordering with the complete, valid sequence from the source.
Scenario 2
If you only want to deploy one specific rule (e.g. from a Git branch), you must change its sort order in the deployment package to match the next available number in the target org.
Solution
In the target org navigate to to Setup > Duplicate Rules
Count the active rules for that object (e.g., if there are 2 rules, they are
Order 1andOrder 2).Open the
.duplicateRule-meta.xmlfile in your deployment package.Read our guidance on how to download your deployment package from Gearset. Note that you may need to amend the package locally, for example by using a text editor like VS Code.
Change the
<sortOrder>tag to the next sequential number (e.g. number3).
Other resources
Trailblazer Community forum (Feb 2017)
Trailblazer Community forum (Apr 2018)
Trailblazer Community forum (Dec 2017)
Disclaimer: This error is returned by Salesforce directly, rather than Gearset. Even so, we offer guidance based on our combined experience with the Metadata API. Where possible, we try to help guide you to fix or avoid this error. In the case that this isn't possible, we may need to direct you to Salesforce support for further clarification.