Explanation of the error
This Salesforce validation error that Gearset is surfacing is likely to occur on the Flow metadata type:
The field apiVersion can't be "<xxx>", where <xxx> is a reference to a specific API version.
In this example, Salesforce validation error referenced Email_Message_Alert.
This was because the Flow Email_Message_Alert was referencing the API version 59 within its XML file, while Gearset comparison was run on API version 56 (as shown on below screenshot).
Resolution
If your intention is to simply deploy the Flow to target without having to amend Flow's API version within the XML file - the solution to that is to amend the API version of the comparison in Gearset app, re-run the comparison, and then proceed with the deployment.
Not sure how to amend the API version in your comparison?
Check our guidance from a separate support article on how to override the API version in Gearset's comparison, and it should help.
Another use case we've seen
If may also happen that you've run your Gearset comparison on an API version lower than the API version referenced in the Flow's XML file.
On below example, the comparison was run on the API version 58, while the API version within Flow's XML is actually version 59, which is what causes the validation to fail.
You can resolve this error by changing the API version within the Flow's XML to version 58, and then re-running your Gearset comparison on the same API version 58.
Note: If you're coming across the same validation error, but your use case is different, and the solution described in this support article doesn't work for you - please, contact us via in-app chat and we'll be happy to help!
Are you not seeing changes made to the Flow after updating API version of the comparison?
It may happen that you're migrating your Flow from a Salesforce org to another environment (for example a Git branch), and after amending the API version of the comparison to version 59, you're not seeing the changes made to the Flow in question.
If that's the case, it's possible that the API version of your source Salesforce org is lower than version 59.
Or it can be that both source org and the target environment of the comparison are on lower API version than 59, while the Flow's version referenced in the XML file is 59.
How to resolve this blocker?
In this particular scenario, in order to avoid having to amend the API version of the Flow to a lower version (so that the Flow's API versions matches the API version of your source and target environment), the next step would be to update your source org's API version to 59.
Salesforce's documentation will guide you through the steps to update the API version.
Once your Salesforce org's API version is updated to version 59, make sure that the target environment is also on API version 59 before you re-run the comparison and re-try the deployment.
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.