Dependency
A dependency in Salesforce is a relationship between two metadata components where one references or relies on the other to function.
Definition
A dependency in Salesforce is a relationship between two metadata components where one references or relies on the other to function. Apex classes depend on the objects and fields they query; validation rules depend on the fields they reference; Flows depend on the objects, fields, and Apex actions they call; permission sets depend on the objects, fields, and apps they grant access to. Salesforce tracks these dependencies and exposes them through the dependency view in Setup, the MetadataComponentDependency object in the Tooling API, and the deployment validation step.
Dependencies matter because they govern what you can change safely and what you can deploy. Deleting a field that a Flow references fails with a dependency error. Deploying an Apex class that uses an unreleased object fails with a missing-dependency error. Packaging a custom feature requires every dependency to either ship in the same package or already exist in the target org. Anyone managing change in a Salesforce org spends a fair amount of time chasing dependencies.
Working with dependencies in Salesforce metadata
Types of dependencies the platform tracks
Salesforce tracks references between most metadata components: Apex Class to Object, Field, Apex Class, Custom Setting; Flow to Object, Field, Apex Action, Subflow; Validation Rule to Field; Permission Set to Object, Field, App; Layout to Field, Action; Custom Field to other Custom Field (in formulas). Some dependencies are explicit (a Flow's element references a specific field), others are inferred at compile time (Apex against a custom object).
The Where Is This Used button in Setup
Most metadata components in Setup have a Where Is This Used button (Lightning) or View Dependencies button (Classic). Click it and you get a list of every component that references the current one. This is the fastest way to scope the impact of a planned change: before deleting a field, click Where Is This Used to find the Flows, validation rules, page layouts, and Apex that would break.
MetadataComponentDependency in the Tooling API
The Tooling API exposes MetadataComponentDependency for programmatic dependency analysis. Query it with SELECT MetadataComponentId, MetadataComponentName, MetadataComponentType, RefMetadataComponentId, RefMetadataComponentName, RefMetadataComponentType FROM MetadataComponentDependency to get every recorded reference. Salesforce DX and third-party governance tools (Strongpoint, Elements.cloud) build their dependency graphs from this surface.
Deployment dependencies and the manifest
When you deploy a metadata package (a manifest XML or a Salesforce DX project), the platform checks that every referenced component either exists in the target org or is part of the same deployment. Missing dependencies fail the deployment with a precise error. The standard practice is to deploy in dependency order: the parent objects and fields first, then the Apex and Flows that reference them, then the permission sets that grant access.
Field dependencies versus metadata dependencies
The word dependency is also used for controlling and dependent picklists: a Lead Source picklist whose values change based on the Lead Type picklist. This is a different concept from metadata dependencies. The platform tracks the relationship as field metadata (a FieldDependency record), not as a MetadataComponentDependency. Both are dependencies, but they live in different governance surfaces.
Cyclic dependencies and the deployment trap
Two Apex classes can reference each other; two Flows can each call the other as a subflow. Salesforce's deploy planner usually handles these cycles correctly, but some package combinations break. The fix is to deploy both components in the same transaction (a destructive change set or a managed-package install). Cyclic dependencies between managed and unmanaged packages are a known sharp edge: avoid them where possible.
Package dependencies and second-generation packaging
Salesforce DX second-generation packaging (2GP) makes package-to-package dependencies explicit. Each package version declares its dependencies (package names and versions). The Salesforce CLI resolves them during install: dependencies install first, then the package itself. This is closer to npm or Maven than to the older first-generation managed-package model, which had implicit dependencies and required careful manual ordering.
How to find and resolve metadata dependencies before a change
Before deleting or changing any field, object, or class, check dependencies. The Setup UI handles single-component checks; the Tooling API and Salesforce DX handle bulk and automated checks.
- Open the component in Setup
For a custom field, navigate to Setup, then Object Manager, then the object, then Fields and Relationships, then the field name. For an Apex class, Setup, then Apex Classes, then the class name.
- Click Where Is This Used
In Lightning Setup, click Where Is This Used at the top of the detail page. The platform returns a paginated list of every component that references this one, grouped by type.
- Review the impact
Read through the list. Group references by component type to spot the heavy users: a field used in 12 Flows, 3 validation rules, and 2 Apex classes needs careful planning. Components that no longer exist (legacy code) are easy wins; active workflows are not.
- For bulk checks, query MetadataComponentDependency
In the Developer Console or via the Salesforce CLI: SELECT MetadataComponentName, MetadataComponentType, RefMetadataComponentName, RefMetadataComponentType FROM MetadataComponentDependency WHERE RefMetadataComponentName = your-field. Returns the same data as the UI but lets you process it in scripts or reports.
- Plan the change with dependencies in mind
Decide which dependent components stay, which get updated, and which get removed. Document the order: remove or update child references first, then change the parent. Validate against a sandbox before deploying to production.
- Deploy and verify
Use a change set or Salesforce DX deployment. The platform re-checks dependencies during deployment and fails fast if any are missing. If the deployment succeeds, run the affected Flows, classes, and validation rules to confirm behavior matches what you planned.
Single-component check from the Setup detail page. Best for ad-hoc analysis.
Programmatic query of all dependencies. Best for bulk and automated checks.
sf project deploy validate, sf project deploy preview, and dependency-check plugins. Best for CI/CD pipelines.
Strongpoint, Elements.cloud, and similar tools build full dependency graphs across the org for impact analysis.
- MetadataComponentDependency does not cover every reference type. Hard-coded record Ids in formulas, references in dynamic SOQL strings, and runtime field references in Apex are invisible to the dependency API. Static analysis catches the rest; runtime testing catches these.
- Deleting a field that a managed package references requires the package vendor to update first. The platform blocks the delete with a managed-package dependency error. Contact the vendor or uninstall the package before retrying.
- Dependencies on standard objects are not tracked the same way as on custom objects. Many references to standard fields go undetected by the dependency API; verify manually for high-stakes changes.
- Field dependencies (controlling and dependent picklists) and metadata dependencies share the word but not the meaning. Searching Setup for dependency surfaces both, which trips up new admins.
Trust & references
Straight from the source - Salesforce's reference material on Dependency.
- MetadataComponentDependency ReferenceSalesforce Developers
- View Component DependenciesSalesforce Help
About the Author
Dipojjal Chakrabarti is a B2C Solution Architect with 29 Salesforce certifications and over 13 years in the Salesforce ecosystem. He runs salesforcedictionary.com to help admins, developers, architects, and cert/interview candidates sharpen their fundamentals. More about Dipojjal.
Test your knowledge
Q1. What is a Dependency in Salesforce metadata?
Q2. Why do dependencies matter for deployments?
Q3. What's the best way to handle dependencies?
Discussion
Loading discussion…