Error overview
You may run into this validation error when your deployment attempts to create a component that carries a namespace prefix that isn't registered in your target org.
Most commonly, this is because the managed package that owns the namespace isn’t installed in the target org.
In the screenshot below, we're seeing an error referencing components with prefix cxn__ (for example: cxn__Agent_ID__c) and the entire error message reports as:
Cannot create a new component with the namespace: cxn. Only components in the same namespace as the organization can be created through the API
In this specific example, the error message is thrown against a number of Custom fields.
Note: The namespace cxn is used as an example here. The actual error message you may be running into can reference any other namespace that is not installed or found in the target org you're deploying to.
Explanation of the error
Salesforce’s Metadata API only allows a namespaced component to be created in an org if that org either:
has that namespace as its own org namespace (e.g. it’s the org that owns or develops the package), or
has the managed package that registers that namespace installed.
If neither is true, any attempt to create a new component under that namespace is rejected by Salesforce API. This is expected and documented namespace enforcement behaviour of the Metadata API (see Salesforce’s developer docs on understanding namespaces and on registering a namespace), rather than a bug in the package or in Gearset’s deployment behavior.
In practice, this error is expected to show up when a namespaced component genuinely exists in one org (e.g. Prod, where the relevant managed package may be installed), but the package isn’t installed in the target org Gearset is attempting to deploy to (e.g. Sandbox). This results in Salesforce’s API refusing the creation once the deployment runs, because the target has no matching namespace to create it under.
This can also produce cascading validation errors in the same validation run. Any other metadata that references the missing namespaced field (for example a ReportType built on a cxn__<xxx>__c field) would also fail with a message like: In field: field - no CustomField named User.cxn__Agent_ID__c found - because from the target org's perspective, the field it depends on doesn’t exist there.
Resolution
Since the target org cannot create a component under a namespace it doesn’t have registered, this isn’t something Gearset can resolve automatically.
The namespaced component(s) need to be excluded from that particular deployment package. Or the managed package needs to be installed in the target org first, if that’s genuinely the intended deployment outcome.
Workaround for org-to-org / Git-to-org deployments (Compare and deploy)
Run the comparison via Compare and deploy between the same source environment and target org.
On the comparison results screen, click on Manage custom filters (the cog icon), then on the metadata type that is failing (e.g. click on
Custom objectif the failing component is aCustom field) click on Specify named items and rule tab - from there you can deselect the failing namespaced component(s), and any dependent metadata that references them, before re-validating your deployment.Before deploying, it’s worth checking whether those components are genuinely expected in the target org:
If the managed package isn’t meant to be installed in the org you're deploying to, excluding the components is the right long-term approach. They’ll need excluding on every future deployment between these two orgs, so consider building a custom metadata filter that doesn't include these components if you're making more than one deployment.
If the package should be installed in the target org, install/enable it there first and re-run the validation in Gearset. The failing components should then deploy normally as an update to an existing package, which would help fix the validation error.
Once you're ready, re-run the validation and deploy to a target org with the namespaced components excluded.
Workaround for a PR failing validation in a Gearset Pipeline (CI job)
If it's a PR that fails on the validation stage in your Gearset Pipeline, the exclusion of the failing components needs to be configured on the CI job's metadata filter.
There are two ways to do this, and a Team Owner (for team-shared Pipelines), or the Pipeline owner will usually need to make the change on the CI job's filter.
Recommended approach
Exclude the “Items that are missing in the target” Problem Analyzer from the CI job’s Problem Analyzer template. This stops Gearset from flagging (and attempting to create) namespaced components the target can never actually receive, and doesn’t require maintaining a list of specific component names.
Create or edit a Problem Analyzer template with that analyzer unchecked (requires an Automation Platform license) - see Problem analyzer templates.
Assign the template to the CI job - on CI jobs page click on the CI job > Edit settings > navigate to the Advanced tab, select a pre-saved problem analyzer template from the dropdown and click Save CI job.
Alternative approach (more manual task, so avoid if possible)
Exclude the specific failing components directly in the CI job’s metadata filter, so that job stops trying to deploy them at all.
Open the CI job > Edit settings > Metadata filters tab, add the components to exclude (check: using regex in metadata filters), then save the filter, and save the CI job - see Manage custom filters in CI jobs and What is a metadata filter for more context.
This only works reliably if the set of affected components is stable. This means that any new namespaced components added later on in time to your deployment package will need to be added as exclusions to your custom filter too.
It’s worth confirming whether these managed package components are genuinely required in the lower Pipeline environments at all. If they’re only present because they exist further up the pipeline (e.g. in Prod org) and aren’t meant to be deployed all the way down, excluding them from Pipeline related CI job filters is the correct end state rather than just a workaround.
Workaround for Dev Sandbox Updates
If this error surfaces when a Dev Sandbox Update runs in your Gearset Pipeline, the fix is the same as above - it just needs to be applied to a different CI job.
A Dev Sandbox Update doesn't have its own separate validation configuration. It uses the Problem Analyzer template and metadata filter of the CI job that's directly linked to that Dev org in your pipeline - usually the first static environment (CI job) in the pipeline. See Getting started with Developer Sandbox Updates in Pipelines for more on how Dev Sandbox Updates work.
To resolve it, follow these steps:
Identify the CI job in your pipeline that's directly linked to the Dev org where the update is failing (usually the first static environment in the pipeline).
Edit that CI job's filter, following the same steps as mentioned above in workaround for a PR failing validation in a Gearset Pipeline (CI job) - either exclude the "Items that are missing in the target" Problem Analyzer from CI job's Problem Analyzer template (recommended), or excluding the specific failing components directly in its metadata filter.
Once the CI job's filter or Problem Analyzer template is updated, re-run the Dev Sandbox Update.
Disclaimer: This error is returned by Salesforce directly, rather than Gearset. Even so, we offer guidance based on our combined experience with the Metadata API. Where possible, we try to help guide you to fix or avoid this error. In the case that this isn't possible, we may need to direct you to Salesforce support for further clarification.