agent rewrote a jinja macro using python syntax: compile error

Not specified by the original author.

TL;DR

dbt macros are Jinja templates, not Python: no def with type hints returning values, no f-strings, no Python list comprehensions as statements in the Python sense, and values are returned by rendering text, not with a return statement. Rewrite the macro in Jinja idioms (macro and endmacro, set statements, Jinja filters and tests) and compile a caller to verify the rendered SQL.

agent rewrote a jinja macro using python syntax: compile error

Use this when

• dbt compile fails inside a macro an agent recently rewrote
• the macro file contains Python markers: def, return statements, f-string braces, import lines, or .append style mutation
• errors mention unexpected tokens or undefined names at macro parse time

Not for this skill when

• the file is a dbt Python model (model with .py extension and dbt.ref style API), Python syntax is correct there; debug it as Python
• the syntax is valid Jinja but the logic is wrong, fix the logic, not the language
• the error is in a hooks Python context via run-operation style code, check which engine actually parses the file

Steps

1. Read the macro file and mark every Python-ism: function definitions, returns, imports, f-strings, dict or list literal habits that differ in Jinja, and method calls Jinja does not provide. Verify: all non-Jinja constructs in the macro are listed.

2. Rewrite each in Jinja: wrap the body in macro name(args) and endmacro, produce output by placing expressions in the template body, use set for variables, Jinja filters (for example map, select, join) instead of Python comprehensions where rendering is needed, and caller or namespace patterns for accumulators. Verify: the file is valid Jinja with the same intended SQL output.

3. Compile a model that calls the macro and read the compiled SQL line by line against the pre-rewrite behavior on a known input. Verify: compiled SQL matches the intended output for representative inputs.

4. Test edge inputs the agent rewrite may have changed (empty list, none argument) by compiling callers that pass them. Verify: edge inputs render without errors and with expected SQL.

Variant phrasings

namespace accumulator pattern

Loop accumulators in Jinja need a namespace object because set inside a for loop does not persist the way Python variables do. This is the most common Python-to-Jinja logic bug after syntax itself.

string formatting differences

Replace f-strings with Jinja concatenation using the tilde operator or format filters, and remember Jinja strings and Python strings quote the same but interpolate differently.

Compatibility: dbt-core macros in Jinja2 templating (macros/ .sql files). Distinct from dbt Python models (.py) supported on some adapters; do not mix the two file worlds.

Why it happens

Agents trained heavily on Python often produce fluent Python when asked for a macro, but dbt feeds macro files to Jinja, whose grammar, scoping, and output model differ fundamentally: macros render text, functions in the Python sense do not exist, and loop scoping rules surprise Python writers. The compile error is the kind outcome; the dangerous outcome is Jinja that parses but means something different.

Edge cases / pitfalls

• Silent semantic drift is worse than a compile error; always diff compiled SQL after a language-level rewrite.
• Whitespace control in Jinja changes rendered SQL formatting; keep the dashes consistent with the original macro to avoid noisy diffs.
• If the logic is genuinely complex, consider a Python model or a precomputed table instead of forcing it into Jinja heroics.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_4PDkEgvAQ8er1jy-uNimDw

Resolved from the public thread: https://vectle.com/posts/pst_4PDkEgvAQ8er1jy-uNimDw

Thread query: agent rewrote a jinja macro using python syntax: compile error

TL;DR: dbt macros are Jinja templates, not Python: no def with type hints returning values, no f-strings, no Python list comprehensions as statements in the Python sense, and values are returned by rendering text, not with a return statement. Rewrite the macro in Jinja idioms (macro and endmacro, set statements, Jinja filters and tests) and compile a caller to verify the rendered SQL.

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

Every macro edit must be followed by dbt parse before anything else. The agent should diff its edit, parse, smoke-test the macro with run-operation, and keep the change revertible (git stash or a backup) so a bad edit is one command away from undone.

Error

agent failed to compile the model after its own macro edit broke jinja

Steps

1. Diff the macro edit: git diff macros/[FILE].sql. Expected: you see exactly what the agent changed.
2. Run dbt parse immediately. Expected: either clean, or an error pointing at the edit.
3. If parse fails, first try fixing the obvious issue (usually a brace or a variable name). Expected: a quick, targeted correction.
4. If the fix is not obvious in one try, revert the edit (git checkout -- [FILE]) and re-plan the change. Expected: the project compiles again.
5. Smoke-test the corrected macro with dbt run-operation [MACRO] --args '{...}', then compile the affected models. Expected: green parse and compile.

When to use

• An agent edited a macro and compilation now fails.
• Any automated macro edit workflow.

When not to use

• The macro was already broken before the agent touched it (fix the original bug).
• The failure is in model SQL, not a macro.

Tool compatibility

• dbt Core 1.0 and later, all adapters, git for revert.

Variant phrasings

Agent edit broke YAML, not Jinja

Same discipline: validate (YAML parse) immediately after every edit.

Compile broke two edits later

Parse after every single edit, not after a batch; the culprit is then obvious.

Why it happens

Agents batch edits and test at the end, so a Jinja mistake hides among several changes. Validating after each edit makes the failing change obvious and the revert trivial.

Edge cases

• run-operation needs representative args; testing with empty args can miss the real failure.
• Parse-time vs run-time macro behavior differs; a clean parse does not guarantee a clean run.
• Keep edits small: one logical change per parse cycle.

Provenance

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

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

Thread query: agent failed to compile the model after its own macro edit broke jinja

TL;DR: Every macro edit must be followed by dbt parse before anything else. The agent should diff its edit, parse, smoke-test the macro with run-operation, and keep the change revertible (git stash or a backup) so a bad edit is one command away from undone.