What causes dbt Circular Macro Dependency?

Macro A dispatches to an adapter override macro that calls back into Macro A. Two utility macros that each call the other for shared logic. Macro in a package calling a project macro that calls back into the package macro. Macro dispatch chain (default → adapter → project) creating an unintentional loop. Macro defined in both a package and the project with the same name, causing an indirect cycle via dispatch

How do I fix dbt Circular Macro Dependency?

Map the call chain manually: trace which macros call which until the cycle is found. Extract shared logic into a third macro that neither of the cycling macros depends on. Use dbt's `--debug` flag to see the full macro dispatch chain during compilation. Check for namespace collisions between project macros and package macros with the same name. Avoid calling generic utility macros from within adapter dispatch macros to prevent indirect cycles

Medium severityconfiguration

Power BI Refresh Error:
dbt Circular Macro Dependency

What does this error mean?

dbt detected a circular dependency between macros — Macro A calls Macro B, which (directly or indirectly) calls Macro A again. dbt cannot resolve the call order and raises a compilation error.

Common causes

1Macro A dispatches to an adapter override macro that calls back into Macro A
2Two utility macros that each call the other for shared logic
3Macro in a package calling a project macro that calls back into the package macro
4Macro dispatch chain (default → adapter → project) creating an unintentional loop
5Macro defined in both a package and the project with the same name, causing an indirect cycle via dispatch

How to fix it

1Map the call chain manually: trace which macros call which until the cycle is found
2Extract shared logic into a third macro that neither of the cycling macros depends on
3Use dbt's `--debug` flag to see the full macro dispatch chain during compilation
4Check for namespace collisions between project macros and package macros with the same name
5Avoid calling generic utility macros from within adapter dispatch macros to prevent indirect cycles

Frequently asked questions

How do I trace a macro call chain in dbt?

Run `dbt compile --debug` and look for `Dispatch: searching for macro` log lines. The debug output shows the full dispatch resolution chain and will reveal where the cycle occurs.