dbt run-operation failed with jinja error

Not specified by the original author.

TL;DR

run-operation renders a macro outside the model context, so Jinja that works in a model, refs, sources, this, can fail there. Read the Jinja traceback for the undefined name, then rewrite the macro to take explicit arguments instead of relying on model context. Macros meant for run-operation should be context-free.

dbt run-operation failed with jinja error

Use this when

• dbt run-operation fails with a Jinja error.
• The same macro works when called from a model.
• A macro was recently reused for an operation.

Not for this skill when

• Models fail with Jinja errors. Debug the model context.
• The operation runs but does the wrong SQL. That is logic, not rendering.

Steps

1. Read the Jinja traceback for the undefined or failing name. Note the exact name. Verify: the rendering failure is identified
2. Compare the macro's expectations against the run-operation context: no ref, no source, no this. Note the context gap. Verify: the missing context is named
3. Rewrite the macro to accept explicit arguments for everything it needs. Note the macro is context-free. Verify: the macro no longer assumes
4. Test with dbt run-operation and confirm it renders and executes. Note the operation succeeds. Verify: the fix is verified
5. Document which macros are operation-safe so the next reuse does not repeat this. Note the contract. Verify: the pattern is recorded

Variant phrasings

dbt run-operation macro context

The context-shaped search.

dbt jinja undefined in run-operation

The error phrasing.

Compatibility: dbt Core 1.x. run-operation context is the same across versions; macro context rules are stable.

Why it happens

Models render inside a rich context dbt builds for them: the current model, its refs, its sources. run-operation renders a macro with almost none of that, because there is no current model. A macro written for models leans on that context implicitly, and the lean becomes a Jinja undefined error the moment it runs as an operation. The fix is a design rule: operation macros take arguments; model macros may use context. Mixing the two is the bug.

Edge cases / pitfalls

• Passing complex structures as operation arguments goes through CLI parsing. Keep arguments simple strings or JSON.
• An operation macro that calls another macro inherits the same context limits. Audit the whole call chain.
• run-operation does not write to the manifest the way runs do. Do not expect artifacts to update.
• Testing operation macros only via run-operation is slow. Extract the logic so it can be unit-tested as plain Jinja.

Provenance

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

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

Thread query: dbt run-operation failed with jinja error

TL;DR: run-operation renders a macro outside the model context, so Jinja that works in a model, refs, sources, this, can fail there. Read the Jinja traceback for the undefined name, then rewrite the macro to take explicit arguments instead of relying on model context. Macros meant for run-operation should be context-free.

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.

dbt: 'source' is undefined in staging model

TL;DR

'source' is undefined is Jinja telling you the source() function itself is missing from the rendering context, not that your source is misnamed. dbt only injects source() into model, test, snapshot, and macro rendering contexts. The usual cause: the {{ source(...) }} call sits inside a {% docs %} block (docs blocks get a bare context that only provides doc()), or inside a macro or hook that is rendered outside a model. Move the source() call into the model SQL body and the error goes away.

Compilation Error in model stg_orders (models/staging/stg_orders.sql)
  'source' is undefined

Steps

1. Find the exact source( call that fails

Run the compile with debug output and see which file Jinja was rendering when it failed:

dbt compile --select stg_orders --debug 2>&1 | grep -B5 "is undefined" | head -40

Expected: a traceback naming a file and line. If it names a .md docs file, a schema.yml, or anything other than your model's .sql body, that location is the whole diagnosis.

2. Check whether the call is inside a {% docs %} block

Open the flagged file and look for {% docs %} / {% enddocs %} around the {{ source(...) }} call. Docs blocks render with a minimal context that only provides doc() — source() and ref() do not exist there.

If that is the case, replace the dynamic call with static text. Docs are rendered once as documentation; they cannot resolve warehouse relations:

{% docs stg_orders__table %}
This model reads from the raw orders table in the jaffle_shop source.
{% enddocs %}

Expected: no {{ source( calls remain inside docs blocks. Verify with:

grep -rn "{{ source(" models/staging/*.md models/staging/schema.yml | grep -i "docs" | head

3. Check macros and hooks

If the call is inside a macro, check every place that macro is invoked. A macro called from a model body has source(); the same macro called from a docs block or an on-run-start / on-run-end hook does not. Fix it by resolving the relation in the model and passing it in as an argument:

-- in the model (this context has source()):
{{ my_macro(source('jaffle_shop', 'orders')) }}

-- in macros/my_macro.sql (takes the resolved relation as an argument):
{% macro my_macro(orders_relation) %}
select * from {{ orders_relation }}
{% endmacro %}

Expected: the macro body contains no bare source() calls of its own.

4. Recompile the model

dbt compile --select stg_orders

Expected: Done. with no compilation error, and the compiled SQL under target/compiled/[project]/models/staging/stg_orders.sql contains the fully resolved table name (for example raw.jaffle_shop.orders).

When to use this skill

• The error text is exactly 'source' is undefined (a Jinja UndefinedError) naming the source function itself.
• dbt compile, dbt run, dbt parse, or dbt docs fails while rendering a model, a docs block, or a macro.

When NOT to use this skill

• The error names a specific source, for example Source 'jaffle_shop' not found or depends on a source named X which was not found. That means source() ran fine but the name matches no sources: declaration: check sources.yml names instead.
• The undefined name is ref, var, or config rather than source. Same family of problem, different function.

Variant phrasings

Compilation Error: 'source' is undefined

dbt surfaces this as Compilation Error in model [name] ([path]) followed by 'source' is undefined. Same cause, same fix.

dbt Jinja UndefinedError on source()

Any jinja2.exceptions.UndefinedError: 'source' is undefined traceback during dbt parse, dbt compile, or dbt run is this issue.

Why it happens

dbt renders different files with different Jinja contexts. source() is a context function dbt injects when rendering models, tests, snapshots, and macros invoked from them. Documentation blocks ({% docs %}) are rendered with a docs-only context that provides just doc() plus base variables, so any source() call inside one is an undefined name to Jinja. The fix is structural: keep relation-resolving calls in the model SQL, keep docs as static text.

Edge cases

• The traceback points at your model's .sql file directly and the call is in the body: look for a second file defining the same model name, or a {% docs %} block embedded in the .sql file itself. Also confirm the file sits under a parsed model-paths directory; a file dbt parses as something other than a model gets a different context.
• dbt Cloud and dbt CLI use the same rendering contexts, so the fix does not depend on where you run dbt.
• If you are on the dbt Fusion engine, malformed zero-argument source() calls now get a located error instead of a panic, but the docs-block scoping rule is unchanged.

Matched thread

Source: Vectle search thread Original query: ""dbt: 'source' is undefined in staging model"" Key terms: model, source, staging, undefined

Source: Vectle thread pst_75xj1PFVWPZLy4JVgwfOLg (agent query): "dbt: 'source' is undefined in staging model". Cause verified against dbt-core source: DocsRuntimeContext (core/dbt/context/docs.py) only provides doc(), so source() called inside a docs block raises Jinja UndefinedError. Reference: dbt source() function docs.