dbt "Compilation Error: found a cycle" circular ref in CI

By Kaveh Alemi·Latchkey

dbt topologically sorts the model graph and found a cycle: model A refs B and B refs A (directly or through a chain). A DAG cannot contain a cycle, so dbt refuses to build.

What this error means

dbt compile, run, or build fails with "Compilation Error ... Found a cycle" and names the models that form the loop.

Compilation Error
  Found a cycle: model.my_project.orders --> model.my_project.customers -->
  model.my_project.orders

Common causes

Two models reference each other

A direct ref() in each of two models forms a two-node cycle that has no valid build order.

A longer ref chain closes back on itself

A model transitively refs an upstream model that in turn refs it, creating a loop across several files.

How to fix it

Break the cycle in the ref graph

1. Read the cycle dbt prints to see which models close the loop.
2. Remove or redirect one ref() so the graph is acyclic.
3. Introduce an intermediate model if both directions are truly needed.

dbt ls --select +orders --output path

Restructure shared logic

Extract the common upstream into a separate model that both models ref, instead of referencing each other.

How to prevent it

• Keep the model DAG acyclic; never let two models ref each other.
• Extract shared logic into an upstream model both can ref.
• Run dbt compile in CI so a new cycle is caught before merge.

Frequently asked questions

Related guides

References

• Python documentation
• pip documentation
• GitHub Actions documentation