Deploy Dependent Picklists Between Salesforce Orgs — Mapping and Controlling Field Intact
A dependent picklist narrows its options based on another field — pick a Region and the Country list filters to match. That convenience is stored as a value-by-value mapping plus a pointer to the controlling field, and moving it to another org is where it falls apart: deploy the dependent field on its own and Salesforce throws it back with no CustomField named … found. The fix is to deploy the controlling field in the same deploy as the dependent field, so the reference resolves — mtdt.io deploys the value mapping intact and recommends the controlling field automatically, since Salesforce's own dependency graph doesn't model that link.
Where the dependency lives
The mapping lives inside the dependent field's own metadata. A dependent picklist's CustomField carries a <controllingField> reference and, for every value, a <valueSettings> block listing which controlling values enable it:
<valueSet>
<controllingField>Region__c</controllingField>
<valueSettings><controllingFieldValue>NA</controllingFieldValue><valueName>USA</valueName></valueSettings>
<valueSettings><controllingFieldValue>EU</controllingFieldValue><valueName>France</valueName></valueSettings>
</valueSet>
For this to deploy, two things have to be true on the target: the controlling field must exist, and the field's metadata has to arrive with its valueSettings intact. A change set deploys the dependent field but won't drag the controlling field along, so you hit the hard failure: In field: controllingField - no CustomField named Region__c found.
mtdt.io deploys the mapping intact
With mtdt.io the dependent field's metadata travels whole — controllingField and every valueSettings ride along, so the mapping lands on the target exactly as it was on the source. mtdt deploys through the Metadata API and recomposes the field from its stored metadata, value settings and all. There's no "deploy the whole object" workaround and no mapping lost in transit.
It recommends the controlling field
Here's the part that keeps the deploy from failing. The dependent field depends on its controlling field, but Salesforce's own dependency graph (MetadataComponentDependency) doesn't model that link — so a tool leaning on it would let you ship the dependent field alone and walk straight into the error. mtdt.io fills the gap: its Impact Analysis reads the dependency out of the field's metadata and recommends the controlling field, one click to include:
Include both and the dependent picklist deploys in one clean shot — the controlling field, the dependent field, and the full value mapping land together, with no no CustomField named … to decode after a failed deploy. It's the same dependency-mapping mtdt does for the value set behind a picklist — see Fix 'Global Value Set Cannot Be Resolved' on Salesforce Deploy.
FAQ
Why does deploying a dependent picklist fail with "no CustomField named … found"?
A dependent picklist's CustomField metadata carries a <controllingField> reference, and that reference has to resolve against the target org. If the controlling field isn't included in the same deploy, Salesforce can't resolve it and rejects the dependent field outright.
Does a change set deploy a dependent picklist's controlling field automatically?
No. A change set deploys the dependent field but won't drag the controlling field along with it, which is exactly what produces the no CustomField named Region__c found failure.
Does Salesforce's dependency graph show that a dependent picklist needs its controlling field?
No. MetadataComponentDependency, Salesforce's own dependency index, doesn't model the link between a dependent field and its controlling field, so a tool relying only on that graph won't warn you before the deploy fails.
How do you deploy a dependent picklist without losing its value mapping?
Deploy the dependent field's metadata as-is, since the mapping (the <valueSettings> for each value) lives inside the field itself rather than in a separate component. The requirement is including the controlling field in the same deploy so the reference resolves — there's no need to redeploy the whole object.
How does mtdt.io handle dependent picklist deploys?
mtdt.io deploys the dependent field's metadata whole, so controllingField and every valueSettings entry ride along intact. Its Impact Analysis also reads the controlling-field dependency directly out of the field's metadata and recommends it for inclusion, since Salesforce's own dependency graph doesn't surface that link.
Deploy dependent picklists without the broken mapping
Let mtdt.io carry the value mapping intact and recommend the controlling field it depends on — so a dependent picklist lands in one deploy, not after a cryptic field error.
Log in to mtdt.io and deploy your dependent picklists.
Was this page helpful?
Let us know how we did