dbt.exceptions.DbtRuntimeError: macro execution failed

TL;DR

The macro itself raised while running, so the fix is inside the macro body, not the call site. Re-run with --debug to get the macro name and line, then open that macro file and guard whatever blew up. Most of the time its an unhandled null or a missing argument default.

Error

dbt.exceptions.DbtRuntimeError: macro execution failed

Steps

1. Re-run the failing command with --debug and capture the full traceback. Look for the macro file path and line number dbt prints just above DbtRuntimeError. Expected: You see something like in macro mymacro (macros/mymacro.sql:12) pointing at the exact line.

2. Open the macro and read the failing line. Check for calls on values that can be null, like .split() on a possibly-empty argument, or a relation that may not exist yet. Expected: You can name the exact expression that raised, e.g. a method call on a None argument.

3. Add a guard: default the argument (macroname(arg=defaultvalue)), wrap the risky call in an if arg is not none check, or use the default() filter. Expected: The macro compiles and the guarded branch handles the null case without raising.

4. Re-run dbt run --select the model that calls the macro, then run the full macro caller set with dbt run --select +themacrocalling_model to catch other callers. Expected: Run succeeds, no DbtRuntimeError, downstream models build.

When to use

• dbt run or dbt test fails with dbt.exceptions.DbtRuntimeError mentioning a macro
• a macro you wrote or edited started raising after a change
• macro works for some models but raises for others

When not to use

• jinja syntax errors at parse time (those say Compilation Error, not DbtRuntimeError)
• the error is a warehouse SQL error with no macro in the traceback
• you only need to change macro arguments at the call site

Tool compatibility

• dbt-core 1.5 and later (error class name stable since 1.0)
• dbt Cloud IDE run logs show the same traceback
• works on all adapters, macro code is adapter-independent

Variant phrasings

DbtRuntimeError vs CompilationError

CompilationError means jinja could not even render the SQL. DbtRuntimeError means it rendered and then blew up while executing. If you see the word Runtime, look at runtime values, not syntax.

macro execution failed with no macro name shown

Run with --debug. Without it dbt trims the traceback and you only get the exception class. The macro name and line are always one --debug away.

Why it happens

Macros execute as python-ish jinja at run time, after the SQL is built. A null argument, a missing relation, or an unhandled edge in your macro logic raises here, not at parse time. dbt wraps it as DbtRuntimeError so it reads like a dbt bug, but it is almost always your macro code.

Edge cases

• If the macro is from a package (dbt-utils etc.), pin the package version before editing; better to override the macro in your own macros/ dir than fork the package.
• DbtRuntimeError can also wrap adapter calls like adapter.get_relation inside a macro, then the real cause is a warehouse permission, check the inner exception.

Provenance

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