Error overview
You may run into a validation error similar to this when validating changes made to a Digital Experience (Experience Cloud) site, most commonly on a site's homepage or another page view component.
An example of this error in our app would look like this:
"The component <id> can't be included in the translation variant because it doesn't exist in the primary content."
Explanation of the error
Digital Experience page views store two things together in the same component:
The "primary content", which is the default-language version of the page
One or more translation (variant) overrides - these are language-specific (and in some cases device-specific) versions of that page's components.
Each component placed on the page gets its own unique ID. A translation or variant override refers back to the primary content using that ID.
This error means that the view's metadata contains a translation or variant override that still references a component ID which no longer exists in that same view's primary content.
In other words, the inconsistency is present inside the Digital Experience Bundle component itself. It isn't caused by a missing related component (such as a Navigation Menu, Content Asset, or Network) being left out of the deployment package.
Steps to take in order to validate the above assessment
You can confirm this by re-running your comparison (between the same source and target environments) with a much broader metadata filter. Use Gearset's filter named Default Experience Cloud comparison, which pulls in all Experience Cloud-related metadata types, select the items to deploy, and run the validation against your target org.
Typically, if a missing dependency was the cause, widening the filter would have surfaced or resolved it by allowing Gearset Problem Analyzer to suggest including missing items in your deployment package.
Resolution
To fix this error, you will need to remove the orphaned reference from the affected view's metadata before re-validating your deployment (or before re-validating the PR in Gearset Pipeline).
The amendment needs to be done in source metadata itself, as there is no Problem Analyzer that could resolve it automatically for you.
Workaround in Compare and deploy
Identify the affected view component from the error message (metadata type:
DigitalExperience, component path e.g.site/<site>.sfdc_cms__view/<view>).You can run the comparison and download .zip deployment package directly in Gearset.
Next, open that component's retrieved source file (from the .zip package) and search for the component ID quoted in the error.
Remove only the entry that references that ID from the translation/variant section. Do not remove anything from the primary content section.
Save the downloaded and amended package back into .zip
Once done, navigate to Compare and deploy page in Gearset and use Local files option as the source of your deployment to the target org.
If for any reason Local files option isn't available for you, get in touch with a Team Owner on your Gearset team to check the Gearset permissions page for your team's account.
There is a configurable permission in Gearset called Run Comparison with Local Files that can prevent Team Members from using Local files option for the deployments.
Workaround in Gearset Pipelines
In your Git repository (e.g. Bitbucket, GitHub), open the feature branch associated with the PR that is failing validation.
Locate the metadata file for the affected view (under the site's Digital Experience Bundle folder).
Search the file for the component ID quoted in the error message. Then remove that ID entry from the translation/variant section.
Once the ID is removed from your feature branch, re-validate the PR in Gearset Pipeline.
Note: This workaround has been confirmed to resolve the error by at least one customer, including on repeat occurrences.
Why does this error keep happening?
Some customers have seen this error re-occurring on PRs promoting the same Experience site (e.g. to other upstream Pipeline environments), requiring the same manual workaround to be applied each time.
We don't yet have a confirmed root cause for why the orphaned ID re-appears, or a way to detect and remove it directly from the Experience Builder before it's committed.
If you're affected by repeated occurrences of this error on the same site, please raise a support ticket via our in-app chat referencing this article so that we can gather more diagnostic detail. This should help us investigate:
Whether the stale reference is being reintroduced by an action in Experience Builder (e.g. editing or re-publishing a page without refreshing its translations).
Or whether there's a way to identify and remove the orphaned component ID reference from within Experience Builder through a development of a dedicated Problem Analyzer, so that Gearset could auto-delete the ID prior to the validation of your deployment package (or a PR in Gearset Pipeline).
Helpful resources
Trailblazer Community forum (Apr 2025)
Disclaimer: This validation error is generated by Salesforce during deployment validation, not by Gearset. Gearset surfaces the error to help you identify and resolve the underlying metadata issue before deployment, but the validation rule itself, and what Salesforce will or won't accept, is controlled by Salesforce.