All Collections
Comparisons and deployments
Troubleshooting manual deployments
Troubleshooting manual deployments

A step-by-step guide to troubleshoot common issues on a manual deployment made via Compare and Deploy

Dario Messina avatar
Written by Dario Messina
Updated over a week ago

Is your deployment showing as successful in Gearset but not displaying what you expected in the target org? If so, this article may help you identify and resolve common problems that may arise during manual deployments.

Please refer to this article if you are dealing with a CI job instead.

If the deployment is showing a validation error, feel free to check out our ever-growing section on validation errors, as well as this guide to replicate the error.

Step 1: Check if the metadata item is included in the Deployment Package

Sometimes we make big deployments and we forget to check the list of the deployed items, but in reality it's a good practice to double check that the specific item we expected to show up in the target has made it through the deployment successfully.


Navigate to the "Deployment History" to be able to either check the list on "View details", "Download report" or even better by downloading the "Deployment package" zip file.

Note: For this and more on navigating the Deployment History, check out this article.

If the item is in the package, and the deployment was successful, this means that you should be able to find this item in your target (make sure you are looking at the correct Salesforce org).

The litmus test would be to make a new comparison using Gearset, between the same source and target, and see that the item (previously New or Changed) is now showing up as No Difference.

If this is not the case, then let's proceed the investigation with Step 2.

Step 2: Check if the item is included in the Metadata filter

Having established that the metadata in question is not being deployed (it's not in the deployment package) we can now move onto discovering why things didn't pan out as intended.

The most frequent reason is that the item is missing in the comparison as well.

In fact, in order for Gearset to be able to deploy a given metadata item, Gearset needs to first be able to retrieve that item in the comparison. The way it does that is by using the Salesforce Metadata API (read more about it here).

And the way we choose which metadata type and which item is to be retrieved for the comparison is via the Metadata filter.

So it's time to check that the metadata filter allows Gearset to retrieve what we want to deploy.


Click "View comparison" from the Deployment History, then "Refresh comparison" once the comparison has finished loading.

Note: We have an extensive guide helping you mastering filters, please have a look here.

Common things to check out:

  • If the item is related to a managed package, then include the managed package in the filter, on the right hand side of the filter.

  • If it's included, it may be worth it to check this section on the prerequisites for managed package metadata to appear in your comparison results.

  • In the central section of the filter, for a given metadata type, you want to make sure the item you are looking for is included on that list in case you have that set up as "Named Items". If you are unsure about that, set it as "All Items".

Note: Still cannot find your item? Please have a look here in case you are searching for a metadata within your source control, or here to reproduce it with Workbench.

Once you've properly set up your filter, you can re-run the comparison by clicking the refresh button at the bottom-right side of the filter UI.

Knowing the API name of the item you are looking for will make the search very easy by using the filter on the top right corner of your comparison.

There is a chance you have this item already selected in your comparison. If that's the case, let's move onto the step 3.

Step 3: Check if the Problem Analyzer stripped out the item

Sometimes it may be the case that the problem analyzer is removing one or more items from the deployment, before the the package is built for deployment.

Once you made your selections and clicked on "Next" from your comparison screen, you can have full visibility of the warnings and problem analysis fixes.

Under the necessary assumption, sometimes, the problem analyzer may suggest to remove the item to increase the chance of having a successful deployment.

A typical example is this problem analyzer, which will remove references to the objects that are not in the target, to make the deployment more likely to succeed.

However, once you established this is the cause of your item not being deployed, and if you are sure that those objects are indeed in the target, you may want to decide to not accept the suggestions and to not remove the items (by unticking the checkboxes), therefore adding the items to the deployment package.

Note: You can understand more about problem analyzers here and how to customise your own problem analyzer template here.

Still unsure? Want the team to take a look? Please feel free to reach out anytime in the in-app chat and share the comparison with us!

Did this answer your question?