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.

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.