## 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.

```text
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