Cannot delete this <component>: it is referenced by other components
You're trying to delete or refactor a metadata component (custom field, Apex class, page, flow, etc.) that other metadata still references. The deployment names which components depend on it — that's where you have to refactor before the destructive change can land.
Also seen asdependent components·Cannot delete this·is referenced by other components·Cannot delete custom field referenced by
Salesforce keeps the org self-consistent: you can't delete metadata that other metadata still uses. The deploy fails with a list of dependent components, and the fix is mechanical — break or update each dependency before re-running the destructive change.
Read the dependency list literally
A typical message:
Cannot delete custom field 'Account.Old_Region__c':
- referenced by Apex Class 'AccountTriggerHandler' (line 47)
- referenced by Validation Rule 'Account.Region_required'
- referenced by Report 'Sales by Region'
- referenced by List View 'My Accounts in West'
Each line is a real dependency you'll have to remove or refactor. Order matters — refactor the Apex class first (because it'll fail to compile if you delete dependents in the wrong order), then strip the validation rule, then update the report and list view.
Find dependencies before you start
Don't deploy and watch it fail. Find dependencies upfront via the Dependency API (recommended) or the new Field Usage view in Setup:
- Setup → Object Manager → object → Fields & Relationships → field → "Where is this used?" — surfaces references in the UI for each field.
- VS Code Salesforce extension → command palette → "Show all references" works for Apex symbols.
MetadataComponentDependency(Tooling API) — programmatically queries dependencies. If you maintain a deploy script, run it before your destructive deploy.
The most common surprise: managed-package references
If a managed package's code references your field, you cannot delete the field without first uninstalling the package. The error message will name the package's namespace, but it's not always obvious unless you know what the namespace prefix means.
Atomic destructive deploys
Salesforce supports destructiveChangesPre.xml and destructiveChangesPost.xml in a deploy package. The "Pre" version deletes the metadata before the rest of the package deploys; the "Post" version deletes after. Use Post when you're replacing one component with another (the new one needs to deploy first so the dependents can be repointed). Use Pre when you're removing the dependent metadata in the same package.
When the dependent is a flow
Flows are stubborn — even an inactive flow blocks deletion of the field it references. Either reactivate-and-edit the flow to drop the reference, or delete the flow itself first. Flow versions accumulate; you may need to drop all versions, not just the active one.
A deploy-time-only escape
If the destructive change is genuinely safe (the field is unused at runtime even though metadata still references it), the ignoreWarnings deploy flag won't help — these are errors, not warnings. The escape hatch is to deploy without test runs (testLevel=NoTestRun) — but that bypasses test failures, not dependencies, so it doesn't help here. The dependency check is structural; you have to actually fix it.
