Sometimes it can be hard to be sure if a validation or deployment error has come from Gearset or directly from the Salesforce metadata API. Replicating this with another tool can rule out Gearset as the root of the validation or deployment error.

This article also applies if no validation or deployment error has been received, but the deployment result in the org is not consistent with what the deployment package zip contains.

In this example we will be replicating this deployment error with Workbench to see that this a message straight from Salesforce and not caused by Gearset:

Salesforce Workbench

Workbench is a simple tool that's popularly used to deploy an org's metadata. Like Gearset, it communicates with Salesforce orgs via the Salesforce metadata API.

If a component can be deployed by Workbench on the metadata API, Gearset can deploy it. If Workbench cannot deploy the metadata, Gearset also won’t be able to.

This makes Workbench an ideal tool to debug issues where validation or deployment errors are being returned in your deployment in Gearset, and isolate metadata API limitations.

If the validation or deployment errors returned using Workbench are identical to those generated by Gearset, then it is a good way to confirm that the issue is with the Salesforce org rejecting the deployment and not something Gearset is introducing.

Generate a deployment package

There are a few ways you can download the deployment package .zip that Gearset is uploading to your Salesforce org:

from the Download package button on the deployment summary page before the validation or deployment, or

you can download the package from the Deployment History, or

from the Download package button in the CI job History page (if the CI job failed, you need to generate the same comparison manually via Compare and Deploy)

Deploy the deployment package with Workbench

Once you have downloaded the deployment package you can use these steps to recreate the deployment errors.

Log into Workbench with your target (not the source) org’s credentials, as that's where you will be deploying the package you just downloaded:

Go to https://workbench.developerforce.com/login.php.
Select Production or Sandbox login (selecting Production if you have a developer org) and the appropriate API version, and click Login with Salesforce.

Click on migration, then Deploy.

In the Choose File dialogue, select the deployment package you downloaded.
- Select the Check only checkbox if you want to validate your package without making any changes to the target.
- Select the Rollback on error checkbox if you are deploying/validating to a production org, as otherwise you will receive an error.
- If deploying to a Production Org, Workbench will not allow Test Level = NoTestRun.
Click Next.
You should now see a summary of the options you selected. Once you confirm you can click Deploy to proceed.

Once the deployment completes, you can explore the results for the validation or deployment.

At this point you should be able to replicate the validation or deployment errors you see in Gearset.

Conclusion

If Workbench is showing the same as Gearset, you can now focus on finding out why the Salesforce metadata API is giving us this. You can open a Salesforce support case to ask why Workbench is returning you an error message you do not expect.

To help you debug with Salesforce, it's best to only mention Workbench and not bring Gearset into the picture, as Salesforce won't support Gearset.