compilation error in dbt Jinja: debugging macros

TL;DR

A Jinja macro error means your macro crashed while dbt was rendering SQL, before any query ran against the warehouse. Run dbt compile --select your_model --debug for the full traceback, add a log call inside the macro to trace execution, and re-run. If the error survives an obvious fix, run dbt --no-partial-parse compile to rule out a stale parse cache.

The exact error

Compilation Error
  macro 'my_macro' takes no keyword argument 'limit'

Common variants: macro '...' is undefined, UndefinedError: '...' is undefined.

Root cause, after the fix

dbt builds models in two phases. Phase one is compile: dbt executes your Jinja macros to produce SQL. Phase two is run: that SQL goes to the warehouse. A CompilationError is a phase-one crash, meaning the Jinja program failed, not the SQL. Read the traceback like a program crash (which macro, which line, which argument), not like a query error.

Steps

1. Get the full traceback: run dbt compile --select your_model --debug. Expected output: a Python traceback ending in the macro file name, line number, and the Jinja error. The failing macro is the one named in the last macro frame, not necessarily your model file.
2. Trace macro execution: inside the macro add {{ log("debug: my_arg is " ~ my_arg, info=true) }} at the branch you suspect. Re-run dbt compile --select your_model. Expected output: your messages print at compile time before the error line, showing the actual values flowing through.
3. Isolate the macro: make a scratch model that calls the macro with literal arguments, like {{ my_macro("lit", 5) }}, and compile it. Expected outcome: if the scratch model compiles, the macro is sound and the caller passed something unexpected (None, an unquoted string, or a missing relation).
4. Rule out the stale cache: run dbt --no-partial-parse compile. Expected outcome: a renamed or moved macro that still errors after the fix usually starts working. The partial-parse cache had the old macro graph.
5. Check dispatch and placement: confirm the macro file lives under macros/ and the name matches exactly, including overrides of adapter macros. Expected outcome: a misspelled override name never dispatches, so the old default version runs and your fix appears to do nothing.

When to use

Use this for compile-time Jinja failures: CompilationError, "macro is undefined", UndefinedError in the Jinja context, or SQL that renders wrong because a macro branch misbehaved.

When not to use

Do not use for DatabaseError at dbt run time (the SQL reached the warehouse; that is a query problem, not Jinja). Do not use for connection or adapter errors. Do not use for dbt deps or package-resolution failures.

Tool and version compatibility

dbt-core 1.x. The log() Jinja function with info=true and the --no-partial-parse flag are available across the 1.x line. On dbt Cloud, --debug output appears in the run logs for the compile step.

Variant phrasings

"dbt macro not defined error", "dbt CompilationError macro", "jinja macro failing during dbt compile", "undefined variable in dbt macro", "dbt macro takes no keyword argument".

Edge cases

An adapter.dispatch override in a package can shadow your local macro with the same name; the dispatch order is project macros first, then packages, then the adapter. A macro argument that arrives as None renders as an empty string, which produces invalid SQL at run time rather than a compile error, so None bugs hide until dbt run. Macros defined inside a model file body are only visible to that model; shared macros must live in the macros/ directory.