What causes HookRunError (on-run-start)?

A SQL statement in on-run-start creates or modifies an audit table that does not yet exist in a fresh environment. A Jinja macro called from on-run-start fails because a required variable (e.g. var('env')) is not set. The database connection established at hook time does not have the required role for the hook SQL. A hook that calls CALL stored_procedure() encounters a procedure that was renamed or dropped. An on-run-start hook using run_query() returns an error that is not handled in the macro

How do I fix HookRunError (on-run-start)?

Run the hook SQL manually to confirm it executes successfully in the target environment.. Add CREATE TABLE IF NOT EXISTS guards for any audit or log tables created in on-run-start.. Use {{ var('my_var', 'default') }} to provide fallback values for variables used in hooks.. Check that the dbt runner role has all required permissions before the hook SQL executes.. Temporarily remove the hook from dbt_project.yml and run dbt run to confirm the models work independently.

High severityconfiguration

Power BI Refresh Error:
HookRunError (on-run-start)

What does this error mean?

A SQL statement or macro in the on-run-start hook failed to execute. Unlike on-run-end hooks, a failed on-run-start hook causes dbt to skip all selected models and report the run as failed without executing any nodes.

Common causes

1A SQL statement in on-run-start creates or modifies an audit table that does not yet exist in a fresh environment
2A Jinja macro called from on-run-start fails because a required variable (e.g. var('env')) is not set
3The database connection established at hook time does not have the required role for the hook SQL
4A hook that calls CALL stored_procedure() encounters a procedure that was renamed or dropped
5An on-run-start hook using run_query() returns an error that is not handled in the macro

How to fix it

1Run the hook SQL manually to confirm it executes successfully in the target environment.
2Add CREATE TABLE IF NOT EXISTS guards for any audit or log tables created in on-run-start.
3Use {{ var('my_var', 'default') }} to provide fallback values for variables used in hooks.
4Check that the dbt runner role has all required permissions before the hook SQL executes.
5Temporarily remove the hook from dbt_project.yml and run dbt run to confirm the models work independently.

Frequently asked questions

Is there a way to make dbt continue even if an on-run-start hook fails?

Not natively. A failed on-run-start hook causes dbt to abort the run. As a workaround, wrap the hook SQL in a try/except at the macro level using run_query with error handling, though this is fragile.

Can I use Jinja if/else in on-run-start to skip the hook in certain environments?

Yes — use {{ if target.name == 'prod' }} guards in the hook to make it environment-conditional. This prevents development runs from triggering production-only setup steps.