How to fix CIRCULAR_DEPENDENCY in Salesforce deployments

Two or more metadata components reference each other, so Salesforce can't determine a valid deploy order.

Surfaces during: metadata deploy validation, before any test executes

What it means

CIRCULAR_DEPENDENCY happens when two components, most often Apex classes, custom metadata records, or record types, each require the other to exist first. The Metadata API deploys components in dependency order, and a cycle means there is no valid order that satisfies both.

Apex is the most common trigger because the compiler resolves class references at deploy time: if Class A's signature references Class B and Class B's signature references Class A, neither can compile first standalone, only together in the same deploy transaction.

Diagnosis

Common causes

Two Apex classes reference each other's methods

Class A calls a method on Class B, and Class B calls a method on Class A, so neither can compile before the other exists.

Custom metadata types referencing each other

A custom metadata record on Type A stores a reference to a record on Type B, and a record on Type B references back to Type A.

Record types referencing each other's picklist values

Two record types on related objects each restrict a picklist to values controlled by the other's record type, creating a loop the deploy can't resolve.

The fix

Deploy a stub first to break the cycle
Deploy one side of the pair with a minimal or empty implementation, then deploy the real logic in a second pass.
Combine both components into a single deploy
Package the interdependent classes or metadata into one deployment so Salesforce resolves the whole set together instead of ordering them individually.
```
sf project deploy start --source-dir force-app/main/default/classes/ClassA.cls force-app/main/default/classes/ClassB.cls
```
Refactor to remove the mutual reference
Extract the shared logic into a third class or interface so neither original component depends directly on the other.

In practice

How Serpent prevents this

Serpent tracks which components a task touches and flags interdependent components before they're split across separate tasks, so a circular pair deploys together instead of failing halfway. See the Salesforce deployment error library.

No-code CI/CD pipeline builder in Serpent

Prevention

Design shared logic into a common base or interface upfront

When two classes need to call each other, extract the shared contract into an interface or utility class from the start instead of wiring direct references.

Never split a mutually dependent pair across separate tasks

Keep components that reference each other in the same branch and the same deployment unit so they never get promoted independently.

Map cross-references before designing custom metadata relationships

Sketch the reference direction between custom metadata types before building them, so a two-way dependency is caught on paper, not at deploy time.

Common questions

CIRCULAR_DEPENDENCY, answered

Does splitting a deployment into smaller change sets fix CIRCULAR_DEPENDENCY?

No, it usually makes it worse. Splitting interdependent components across separate deploys is what creates the cycle in the first place; bundling them into one deploy is the fix.

Can three or more components form a circular dependency, not just two?

Yes. A cycle of any length, A depends on B, B depends on C, C depends back on A, triggers the same error; the fix is still to deploy the whole cycle together.

Does the Salesforce CLI resolve circular Apex dependencies automatically?

No. The CLI deploys whatever set of files you point it at as one transaction; it doesn't reorder or stub components for you, so both sides of the pair must be included explicitly.

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

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

Start free Book a demo