dbt.exceptions.CompilationError" jinja macro

TL;DR

A Jinja macro crashed while dbt was compiling. Get the full traceback with --debug, find the innermost macro frame, reproduce the failure with dbt run-operation, fix the macro, and recompile.

Error

"dbt.exceptions.CompilationError" jinja macro

Steps

1. Re-run with dbt compile --debug (or the failing command with --debug) to get the full traceback. Expected: the traceback names the macro file and line.
2. Open the macro at that line and read the surrounding logic. Expected: you see the expression that failed (often an undefined variable or a bad filter).
3. Reproduce in isolation: dbt run-operation [MACRO NAME] --args '{...}' with representative arguments. Expected: the same error reproduces without compiling the whole project.
4. Fix the macro: define the variable, guard with {% if %}, or correct the filter. Expected: the isolated run-operation succeeds.
5. Run dbt compile for the full project. Expected: compilation completes with no macro errors.

When to use

• dbt fails with dbt.exceptions.CompilationError and the traceback goes through a macro file.
• You just edited a macro in macros/.

When not to use

• The traceback points at a model file (fix the model SQL).
• The error is a warehouse Database Error (the SQL compiled fine).

Tool compatibility

• dbt Core 1.0 and later, all adapters. run-operation works on any macro.

Variant phrasings

CompilationError in dispatch or adapter macro

Check adapter macro overrides; the failing macro may live in the adapter package, not your project.

Macro failed only for one model

The macro receives different arguments per call site; reproduce with that model's arguments.

Why it happens

Macros execute arbitrary Jinja during compilation. An undefined variable, a bad default, or a filter applied to the wrong type raises inside the macro, and dbt wraps it as a CompilationError.

Edge cases

• Macros behave differently at parse time vs run time; guard parse-only logic with {% if execute %}.
• Default arguments are evaluated at definition time; a bad default breaks every call.
• Recursion between macros produces this error with a deep, repeating traceback; look for the repeating frame.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_4Y0TjgDpT5bkERIC510bPA