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.
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.xmlfiltering - location of the
package.xmlfile, or which metadata is stated in it
- Other issues with the structure of your source control repository
- Corrupted item file
.forceignorefile 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.
- 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, or in both but different versions
- 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.
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 allstandard 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.xmlis just filtering that is applied afterwards. (See this support document.)
It’s associated with a managed package, and the managed package was not included in the metadata comparison filter
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.
(If you’re comparing metadata in source control, due to difficulties detecting whether metadata is in a managed package, it may appear in the results even if the
None button is selected in the 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 or
Named items. If
Named items, 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.
Source-control related settings
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.
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.
- Is the
Filter comparison by package.xmlticked on the Compare metadata page?
- If yes, is your specific metadata type listed in the
- 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.xmlfeature guide and support doc.
package.xmlonly 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.xmldoes not separately retrieve it.
package.xmlneeds to be located correctly within your repository, since it is also used by Gearset to locate your metadata folder. If you have a
package.xmlfolder 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.xmlfiles, 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
- If it's a custom object in a SFDX format repo, not including the
.object-meta.xmlfile for each object.
- In a SFDX format repo, a
.forceignorefile 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
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 itemsincludes everything, regardless of difference type. Therefore, if you were searching in the
Changed itemstab but your item is detected as
Deleted, you would be able to find it (and see what the difference type is) by searching in
- Looking at the wrong metadata type. Lots of metadata types have similar names. For example, people sometimes mix up
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.
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.
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
Choose with the namespace listed.
In addition to this, to make sure you see managed package metadata in the comparison results:
- The managed package should be installed in both source and target.
- The version of the managed package should be the same in both source and target. (The metadata may be hidden from the comparison results if the versions are different, because a detected difference might be due to a version difference rather than a user customization.)
- If the
Installed packagemetadata type is not included in the metadata filter, Gearset cannot tell which version the managed package is, and will show the metadata even if the versions are different or the managed package is not present in both source and target. This is therefore a workaround for the two requirements above. This is described in this separate support article.
- The installed package file itself will show even if the above two conditions are not met.
For more on comparing managed package metadata, see our support article.
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
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 translationand
Custom objectin your metadata comparison filter. (They’re both included in the
- Enable the translation workbench in both source and target orgs.
- Make the language
Activein 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: