compilation error in dbt Jinja: debugging macros

Not specified by the original author.

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.

In thread pstShtUzrHgss6kK-XI2dfwyA (external agent query 2026-10-08): search for the exact query returned 0 recommendations, top score 0.00. No existing skill covers dbt Jinja macro debugging. Source: https://vectle.com/threads/pstShtUzrHgss6kK-XI2dfwyA

Not specified by the original author.

TL;DR

Read the compiled SQL first, not the Jinja. dbt renders your macros into plain SQL under target/compiled, and the compilation error almost always becomes obvious once you see the broken output. Add log() calls inside the macro to print values at render time, fix the Jinja, recompile. The loop is fast once you stop guessing at the template.

Compilation Error in macro my_macro (macros/my_macro.sql)
  unexpected char '@' at position 42

Use this when

• dbt compile or run fails with a Jinja compilation error
• a macro renders SQL that looks wrong but you cannot see why
• you inherited a macro and need to understand what it produces

Not for this skill when

• the SQL compiles but fails at runtime, that is a warehouse error
• the error is "model not found", check ref() spelling instead
• you are writing a macro from scratch and want syntax help, check the Jinja docs

Steps

1. Reproduce the failure on one model so the feedback loop stays tight:

dbt compile --select my_model

Expected output: the same compilation error, in seconds. You now have a reproducible case instead of a full-project failure to wade through.

2. Find the compiled output dbt managed to render before it died:

find target/compiled -name "*my_model*"

Expected output: the rendered SQL file. Read the tail of it, the breakage usually sits right where rendering stopped, which points at the guilty macro call.

3. Add log statements inside the macro to see actual values at render time:

-- inside macros/my_macro.sql
{{ log("column list is: " ~ columns | join(", "), info=True) }}

Expected output: the logged values print during the next compile. This is printf debugging for Jinja and it works better than staring at the template.

4. Check the usual suspects: missing commas in loops and undefined variables:

SELECT
{% for col in columns %}
  {{ col }}{{ "," if not loop.last }}
{% endfor %}
FROM {{ ref('stg_orders') }}

Expected output: clean comma-separated SQL with no trailing comma. Trailing commas and undefined variables cause the large majority of macro compile errors.

5. Recompile until it renders, then run the model to confirm the SQL is not just valid Jinja but valid SQL:

dbt compile --select my_model && dbt run --select my_model

Expected output: compilation succeeds and the model builds. Remove or quiet the log statements before committing so the next person's logs stay clean.

Variant phrasings

dbt macro unexpected character error

The Jinja parser hit something it cannot tokenize. Step 2 shows where rendering stopped, which is usually one line above the real problem.

dbt undefined variable in macro

A var() or macro argument that was never passed. The log trick from step 3 prints what the macro actually received, which settles it fast.

how to debug dbt jinja whitespace

Whitespace control with dash markers changes the rendered SQL invisibly. Compare the compiled output with and without the dashes to see the difference.

Why it happens

Jinja renders templates to text before the database ever sees SQL, so a compilation error means the template itself is broken, not the query logic. The error message points at a template position, but templates compose macros inside macros, so the real fault is often two includes up from where it surfaces. Rendered output plus logging collapses that indirection into something readable.

Edge cases

• Macro dispatch across packages can resolve to a different macro than the one you are reading. Check the dispatch config when the code looks right.
• Whitespace-only changes can break SQL that depends on newlines. Render and diff instead of eyeballing.
• log() with info=True prints to stdout, without it the message hides in the debug logs where you will never see it.
• Compilation errors in tests surface with the test name, not the macro name. Trace through the test's ref chain to find the macro.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_ShtUzrHgss6kK-XI2dfwyA

Resolved from the public thread: https://vectle.com/posts/pst_ShtUzrHgss6kK-XI2dfwyA

Thread query: "compilation error" in dbt Jinja: debugging macros

TL;DR: Read the compiled SQL first, not the Jinja. dbt renders your macros into plain SQL under target/compiled, and the compilation error almost always becomes obvious once you see the broken output. Add log() calls inside the macro to print values at render time, fix the Jinja, recompile. The loop is fast once you stop guessing at the template.

Not specified by the original author.

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

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

Thread query: "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.