How to fix DEPENDENCY_EXISTS in Salesforce deployments

Salesforce won't delete a field, object, or picklist value because another component still references it.

Surfaces during: metadata deletion, via destructiveChanges.xml or Setup

What it means

DEPENDENCY_EXISTS blocks the deletion of metadata, a custom field, object, record type, or picklist value, because something else in the org still points to it: a formula, a validation rule, a flow, a report, or a page layout. Salesforce protects data integrity by refusing to remove a component out from under its dependents.

It only fires when the metadata already lives in the target org and something is deleting it, whether through Setup, a destructiveChanges.xml deployment, or the Tooling API; it never appears on a plain additive deploy of new metadata.

Diagnosis

Common causes

Formula field or validation rule references it

A formula field, validation rule, or workflow rule reads the field or object being deleted, and Salesforce refuses to break that reference.

Reports or list views still use it

A saved report, report type, or list view filters or displays the field, keeping it "in use" even if no one runs it anymore.

Flow or Apex still reference the field

A Flow, Process Builder process, or Apex class queries or assigns the field, so the platform treats it as a live dependency.

The fix

Find every dependent with Salesforce's dependency check
Use the "Where is this used?" tool in Setup on the field or object to list every formula, flow, report, and layout that references it.
Remove or update each dependency first
Edit or delete the referencing formula, flow, validation rule, or report so it no longer points at the component.

Delete the component in a separate step

Once no dependents remain, delete the field or object on its own, after the dependency cleanup has landed in the target org.

<!-- destructiveChangesPost.xml, deployed after the dependency cleanup lands -->
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
  <types>
    <members>Account.Legacy_Score__c</members>
    <name>CustomField</name>
  </types>
  <version>62.0</version>
</Package>

In practice

How Serpent prevents this

Serpent runs a preflight dependency check before a deletion reaches a shared org, so a field that's still referenced surfaces as a blocked task instead of a failed production deploy. See the Salesforce deployment error library.

No-code CI/CD pipeline builder in Serpent

Prevention

Run the dependency check before scheduling any field or object retirement

Make "Where is this used?" a required step in the deprecation checklist, not a debugging step you reach for after the first failure.

Retire references before scheduling the deletion

Land the cleanup of formulas, flows, and reports as its own deployment, then schedule the destructive deletion as a separate, later release.

Use the Metadata API's two-phase destructive deploy pattern

Deploy destructiveChangesPre.xml for pre-cleanup and destructiveChangesPost.xml for the final removal, matching Salesforce's own recommended deletion sequencing.

Common questions

DEPENDENCY_EXISTS, answered

Why does DEPENDENCY_EXISTS not show up until I deploy to a sandbox or production?

Because sandboxes and production often carry reports, flows, or layouts that don't exist in a scratch org or dev sandbox, so the dependency is invisible until you deploy somewhere those dependents actually live.

Does the "Where is this used?" tool catch every kind of dependency?

It catches most declarative dependencies, formulas, flows, layouts, reports, but it can miss dynamic references inside Apex, like a field name built from a string in SOQL, so search your codebase too before deleting.

Can I delete a field that's only referenced in an inactive Flow version?

No. Salesforce checks all versions of a Flow, not just the active one, so an inactive version referencing the field still blocks the deletion.

Start free. No credit card, no install, no commitment.

Set up in under 15 minutes. No DevOps hire needed.

Start free Book a demo