Salesforce deploy "CIRCULAR_DEPENDENCY" in CI

Salesforce orders components by dependency before deploying. When components form a cycle (A needs B, B needs A), no valid order exists and the deploy fails with CIRCULAR_DEPENDENCY.

What this error means

The deploy fails with "CIRCULAR_DEPENDENCY: circular dependency detected" naming components that reference each other.

Deploy failed.
Type        Name          Problem
CustomField Object_A.B__c CIRCULAR_DEPENDENCY: circular dependency detected

Common causes

Mutually referencing metadata

Two objects with lookup fields to each other, or formula fields that reference across a cycle, cannot be ordered, so Salesforce reports a circular dependency.

A self-referencing chain across components

A longer A to B to C to A chain of references also produces a cycle the deployer cannot break.

How to fix it

Split the deploy into two passes

Deploy the objects and base fields first, without the cross-referencing fields.
Deploy the fields that create the cycle in a second pass.
This breaks the cycle into an orderable sequence.

Terminal

sf project deploy start --target-org ci-org --metadata CustomObject
sf project deploy start --target-org ci-org --metadata CustomField

Remove the unnecessary cross reference

If one side of the cycle does not need to reference the other, drop that dependency so a linear order exists.

How to prevent it

Avoid mutual lookups and formulas that create reference cycles.
Stage deploys so base metadata lands before cross-referencing fields.
Review new lookups for cycles before committing.