It’s fairly common that customers contact us because they’re unable to locate a specific metadata item in their Gearset comparison results. This can be a little tricky to investigate, as there are lots of possible reasons!

To make things easier and to save you time, this document lists various possible causes for you to check. We begin with a quick checklist, and then there is further detail on each of these points below.

Before you start, please double-check whether the metadata item you are looking for is actually present in your source/target! We do occasionally speak to customers who cannot find something in the Gearset comparison results due to it being missing from their Salesforce orgs / source control repository.

Summary checklist

Incorrect metadata comparison filter, so metadata item is not retrieved

Required metadata type(s) not included in filter
Managed package not included in filter
Named item not included in filter
Regex filtering

Source control settings

Package.xml filtering - location of the package.xml file, or which metadata is stated in it
Other issues with the structure of your source control repository
Corrupted item file
.forceignore file set to exclude the file/directory

Metadata item is present in comparison results, but you’re struggling to find it

Item is a subcomponent rather than a top-level item
Searching for the user interface (UI) name rather than the API name
Searching in the wrong tab (e.g. Changed rather than New)
Looking at the wrong metadata type
Having a search filter applied without realizing

Metadata item won’t appear in comparison results (regardless of comparison filter)

Metadata type not supported by the Salesforce metadata API or Gearset
Managed package not in source and target
Managed package present in both source and target but package has different versions (and an incorrect setting for package version item handling is selected on metadata filter)
It’s a permission that’s turned off
It’s a translation that hasn’t been enabled/activated in both orgs

Incorrect metadata comparison filter

Before you kick off a comparison in Gearset, you select a metadata comparison filter. This determines which metadata is requested and downloaded by Gearset from Salesforce or your source control repository.

If your metadata filter does not include your metadata item, it will not be retrieved and so will not appear in your Gearset comparison results. For more general information on Gearset metadata filters, see this separate support article:
Custom metadata filters in Compare and deploy and CI jobs

We also recommend to read through the documentation that provides more information on the retrieval of managed packages in Gearset:
Comparing managed package metadata with Gearset

The required metadata types were not included in the metadata comparison filter

Consider the metadata type of the item you are looking for, and make sure it is included in your metadata filter.

Are you using Gearset’s Default comparison? Check whether your metadata type is included. If not, you can create a custom filter, or use the Compare all standard filter.
Be aware that you may need to include multiple metadata types in your metadata filter to retrieve your particular metadata type, and the metadata types to select may not be what you expect. A classic example is profiles and their subcomponents - see our support article on deploying profiles for further details. For advice on picklists, see this article. For help with standard value sets, see this support document.
Note that even if you are filtering by a package.xml (discussed in further detail later in this article), the metadata filter must include the appropriate metadata types. This is because the metadata filter still determines which metadata is retrieved - the package.xml is just filtering that is applied afterwards (see this support document for more info).

It’s associated with a managed package, and the managed package was not included in the metadata comparison filter

The Gearset Default comparison metadata filter does not include managed packages.

If you want to see metadata associated with managed packages, you should either use the Compare all filter, or create a custom metadata filter.

In a custom filter, you can either select All managed packages, or Choose specific ones.

By selecting any of these two options, Gearset will display detected namespaces (managed packages) below along with their versions in each environment.

Note on the behaviour when comparing managed packages in version control

If you’re comparing metadata in source control (e.g. Git branch selected as source or target), due to difficulties in detecting whether metadata stored in version control is in a managed package or not, such metadata items may appear in the comparison results even if the None button is selected in your metadata filter.

Metadata type set to 'Named items' and your item is not included

Even if you have the correct metadata types selected in the comparison, check whether they are set to All items from source and target or Specify named items and rules.

If you have selected Specify named items and rules, check whether your metadata item has been ticked.

You’re using regex that excludes your item

Check whether you have a regex rule in your metadata filter that’s filtering out your metadata item.

For example, note that exclude regex takes priority over any other filters, so items that match the pattern are excluded no matter what, regardless of whether they were also included individually or via regex.

For more on regex in the metadata comparison filter, see this separate support article.

If you are using a Git version control system (e.g. GitHub or Bitbucket), then the structure of your repository and any package.xml filtering can influence whether metadata is shown in the comparison.

Package.xml filtering

If the source of your comparison is a source control system structured in the metadata API format, you have the option of filtering the retrieved metadata by a package.xml. We explain this feature in this support article.

Please check:

Is the Filter comparison by package.xml ticked on the Compare and deploy page?

If yes, is your specific metadata type listed in the package.xml?
Note that the top-level item must be specified in the package.xml. For example, if you want to retrieve a particular Custom field, you need to specify the Custom object it’s on instead - if you only specify the subcomponent and not the parent object, the subcomponent won’t be visible in your results. There’s more on this in our package.xml feature guide and support doc.
The package.xml only applies a filter to the metadata that’s been retrieved. Therefore, your metadata comparison filter must include your metadata (described in the section above) - the package.xml does not separately retrieve it.
The package.xml needs to be located correctly within your repository, since it is also used by Gearset to locate your metadata folder. If you have a package.xml folder placed somewhere other than the root of your metadata, then Gearset will not be able to locate your metadata. For further details, see our guide to structuring your source control repository. Avoid having multiple package.xml files, as stated in this troubleshooting article.

Structure of your source control repository

It’s important that your source control repository is structured in a correct format, or Gearset may not be able to find your metadata. We have a support article that describes the different possible formats.

For example, if you are using the Salesforce DX metadata format, you must include a sfdx-project.json file, but you shouldn’t include one if you’re using the metadata API format.

Avoid having multiple /src directories or package.xml files in your branch, as then Gearset may have problems determining which instance to render. (There’s more on package.xml in the section above.)

Other potential issues

As described in our article on common problems with viewing metadata in source control additional things to look out for are as follows. See the hyperlinked article for further details.

Corrupted file for a specific metadata item.
If it’s an Apex class in a SFDX format repo, not including .cls-meta.xml for each .cls file.
If it's a custom object in a SFDX format repo, not including the .object-meta.xml file for each object.
In a SFDX format repo, a .forceignore file is set to exclude that file or directory.

The metadata is in a different place in the Gearset comparison results

Sometimes customers report that a metadata item is missing from their comparison results, but when we investigate, we find that it is there after all. This section will give you some tips on where to look for your metadata item.

Your item is a subcomponent, so you may need to locate the parent item first

If your item is a subcomponent (e.g. a custom field), rather than a top-level item (e.g. a custom object), then it may not be listed as its own line item. This is particularly likely if the subcomponent has a difference type of No difference. (We have a separate support article on this topic.)

You should search for the parent item in the Gearset comparison results - the All items tab would be a good place to look - and then expand it out to see the components underneath.

For more information on subcomponents of profiles, see this specific support article.

Searching for the wrong name

Gearset uses the Salesforce metadata API. The metadata items retrieved are labelled in the comparison results with their API names (which may also be called field names), rather than their names in the user interface (labels).

For example, here I have created a new field called New field. However, to find it in the comparison results, I should search for the API name of New_Field.

Otherwise, when looking for New field, the comparison results may show unrelated components, or not display the component I'm looking for at all.

The names may even be completely different - for example, Manage Articles in the Salesforce UI has an API name of EditKnowledge, so the latter is what you would need to search the Gearset comparison results for.

Other common mistakes

Searching in the wrong tab. If you’re struggling to find a metadata item, it’s recommended to try searching in the All items tab. All items include everything, regardless of difference type. Therefore, if you were searching in the Changed items tab but your item is detected as New or Deleted, you would be able to find it (and see what the difference type is) by searching in All items.
Looking at the wrong metadata type. Lots of metadata types have similar names. For example, people sometimes mix up Custom fields and Custom field permissions. Check you are looking at the correct metadata type.
Having a filter applied. Gearset makes it easy for you to find your metadata item in the comparison results by filtering. You can either use the global filter in the top right, or filter each individual column. If you are having difficulty finding your metadata item, check whether you have an active filter. Note that the global filter and the column filters remain even when you change tab, so remember to remove the filter(s) if required.

Example when looking for a Custom field in the right tab:

Example when looking for a the same Custom field in an incorrect tab:

Not present in the comparison results due to its metadata type or setting

On some occasions, due to the specific type of metadata or how it’s currently set in your source/target, your metadata item will not be shown in the Gearset comparison results.

In some cases, you can change a setting to make it visible, or it doesn’t matter that it’s not visible; in other cases, that metadata type is not compatible with the Salesforce metadata API and therefore Gearset, so you will need to make the change manually using the Salesforce UI.

Metadata type not supported

Gearset uses the Salesforce metadata API to retrieve metadata. Not being supported by the Salesforce metadata API is a reason you may not be able to find a metadata item in the comparison results. You should make the change manually using the Salesforce UI.

You can view the list of metadata types not supported by the Salesforce metadata API here. Named credential permissions are also not supported, as mentioned in this support document.

Occasionally, there may be metadata types that are compatible with the metadata API, but not currently compatible with Gearset. For example, it may be a new Salesforce metadata type that we haven’t yet integrated.

If you think your metadata type falls under this category, please feel free to contact us, and we may be able to add support for it.

If it’s associated with a managed package ...

As described earlier in the article, in the Incorrect metadata comparison filter section, if your metadata is associated with a managed package, you should ensure the metadata filter is set to either All, or Choose with the namespace listed.

When setting it to All, you have an option under Package version item handling to Hide items when different or to Show all items.

This allows you to choose to include managed package metadata with different version numbers. However, keep it mind that attempting to deploy mismatching items may fail the deployment.

For more information on comparing managed package metadata, see our support article:
Comparing managed package metadata with Gearset

If it’s a permission turned off ...

If a permission is set to none, it is treated as the absence of a permission rather than a permission set to false, and so it is not returned by the Salesforce metadata API.

For example, if a permission is turned off in a source org and turned on in a target org, it will show in the Gearset comparison results as Deleted rather than Different.

Be aware that if it is turned off in both your source and target, it will not show in the comparison results at all.

If it’s a translation ...

To see your translations in your Gearset comparison results, you should:

Include both Custom object translation and Custom object in your metadata comparison filter. (They’re both included in the Default comparison filter.)
Enable the translation workbench in both source and target orgs.
Make the language Active in both orgs.

In the metadata comparison filter, you may need to set Include managed packages to All, as some translation metadata may have its manageableState property set to beta rather than unmanaged in Salesforce.

For more detailed guidance on migrating translations, please refer to these articles:

Comparing managed package metadata with Gearset

How come Gearset doesn't show my item?

Filtering comparison results by package.xml

Custom metadata filter versus package.xml

How to replicate metadata download speeds with Workbench