What causes ProjectHookError?

The hook SQL references a table, schema, or warehouse object that does not exist in the target environment. The role running the dbt job lacks permission to execute the hook SQL (e.g., CREATE SCHEMA, TRUNCATE TABLE). A Jinja rendering error inside the hook SQL prevents it from compiling correctly. The hook was valid in development but uses a hardcoded schema name that does not exist in production

How do I fix ProjectHookError?

Step 1: Find the hook SQL in dbt_project.yml under on-run-start or on-run-end.. Step 2: Run the hook SQL manually in the target warehouse under the same role as the dbt job to reproduce the error.. Step 3: Fix any permission issues — grant the required privileges to the dbt job's role.. Step 4: Replace hardcoded schema names with Jinja references to target.schema so the hook adapts to each environment.. Step 5: Add error handling if the hook failure should not abort the run by wrapping the hook in a macro that catches exceptions.

High severityexecution

Power BI Refresh Error:
ProjectHookError

What does this error mean?

A SQL statement defined in the on-run-start or on-run-end hook in dbt_project.yml failed to execute, which may cause the entire dbt run to fail depending on the hook's error handling.

Common causes

1The hook SQL references a table, schema, or warehouse object that does not exist in the target environment
2The role running the dbt job lacks permission to execute the hook SQL (e.g., CREATE SCHEMA, TRUNCATE TABLE)
3A Jinja rendering error inside the hook SQL prevents it from compiling correctly
4The hook was valid in development but uses a hardcoded schema name that does not exist in production

How to fix it

1Step 1: Find the hook SQL in dbt_project.yml under on-run-start or on-run-end.
2Step 2: Run the hook SQL manually in the target warehouse under the same role as the dbt job to reproduce the error.
3Step 3: Fix any permission issues — grant the required privileges to the dbt job's role.
4Step 4: Replace hardcoded schema names with Jinja references to target.schema so the hook adapts to each environment.
5Step 5: Add error handling if the hook failure should not abort the run by wrapping the hook in a macro that catches exceptions.

Frequently asked questions

Can I make a project hook failure non-fatal in dbt?

Not natively for all hook types. You can write the hook as a macro that wraps the SQL in a try-except pattern using the run_query() Jinja function and returns a warning instead of raising an exception.

Do on-run-start hooks run before or after source freshness checks?

On-run-start hooks run at the start of dbt run, dbt test, and dbt build. As of dbt v1.8+, a behavior flag controls whether on-run-start also fires during dbt source freshness invocations. Check the dbt deprecations documentation for your version.