What causes Runtime Error?

A macro uses the `exceptions.raise_compiler_error()` or `exceptions.warn()` function to signal an invalid state. An on-run-start or on-run-end hook fails during execution. A dbt package version conflict causes unexpected macro behavior at runtime. Environment variables referenced in dbt_project.yml or profiles.yml are not set in the Cloud job environment. A post-hook SQL statement fails, even though the model itself ran successfully

How do I fix Runtime Error?

Read the full stack trace in the dbt Cloud run logs — runtime errors always include a traceback pointing to the macro or hook that raised the error.. If the error originates in a macro, check whether the macro has explicit validation logic (raise_compiler_error) and what condition triggered it.. Check on-run-start and on-run-end hooks in dbt_project.yml — these run before/after all models and a failure here blocks or partially breaks the run.. Verify all required environment variables are set in the dbt Cloud job environment settings.. Run the affected macro logic manually in your warehouse to isolate whether it is a Jinja logic error or a warehouse execution error.

High severitydbt

Power BI Refresh Error:
Runtime Error

What does this error mean?

Dbt failed during execution due to a macro or hook raising an explicit exception, or from dbt internals hitting an unexpected state — this is distinct from compilation errors (which fail before SQL is generated) and database errors (which fail at the warehouse). The stack trace in the run log identifies the exact macro or hook that raised the failure.

Common causes

1A macro uses the `exceptions.raise_compiler_error()` or `exceptions.warn()` function to signal an invalid state
2An on-run-start or on-run-end hook fails during execution
3A dbt package version conflict causes unexpected macro behavior at runtime
4Environment variables referenced in dbt_project.yml or profiles.yml are not set in the Cloud job environment
5A post-hook SQL statement fails, even though the model itself ran successfully

How to fix it

1Read the full stack trace in the dbt Cloud run logs — runtime errors always include a traceback pointing to the macro or hook that raised the error.
2If the error originates in a macro, check whether the macro has explicit validation logic (raise_compiler_error) and what condition triggered it.
3Check on-run-start and on-run-end hooks in dbt_project.yml — these run before/after all models and a failure here blocks or partially breaks the run.
4Verify all required environment variables are set in the dbt Cloud job environment settings.
5Run the affected macro logic manually in your warehouse to isolate whether it is a Jinja logic error or a warehouse execution error.

Frequently asked questions

My run-end hook fails but all models show as success — is my data correct?

Model data is correct, but the hook's action (grants, audit logging, notifications) did not complete. The dbt Cloud run is marked failed even though models passed.

How do I find which macro raised the runtime error?

Check the dbt Cloud run logs for the Python traceback — it shows the macro file path and line number. If the error says `raise_compiler_error`, search macro files for that string to find the triggering validation.

Can a runtime error in one model block other unrelated models from running?

Only if the error is in an on-run-start hook, which runs before any models. An error in a specific model or post-hook fails that model and its downstream dependencies — parallel DAG branches still run.

Official documentation: https://docs.getdbt.com/guides/debug-errors