## 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

```text
"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