What causes ProjectVariableNotFound?

A new model was added using var() but the variable was not added to the vars section of dbt_project.yml. The variable was defined in a package's dbt_project.yml but the consuming project does not define it, and no default is provided. The variable name in the var() call has a typo compared to the key in dbt_project.yml. A --vars override in a CI/CD job specifies a different variable name than what the model expects

How do I fix ProjectVariableNotFound?

Step 1: Identify the variable name from the compilation error message.. Step 2: Add the variable to the vars section of dbt_project.yml with a sensible default value.. Step 3: Alternatively, provide a default directly in the code: var('my_var', 'default_value').. Step 4: If the variable should differ per environment, configure it as a dbt Cloud environment variable using env_var() or via the --vars flag in the job definition.. Step 5: Run 'dbt compile' to confirm the variable resolves correctly.

Medium severitycompilation

Power BI Refresh Error:
ProjectVariableNotFound

What does this error mean?

A dbt model, macro, or hook used the var() function to reference a project variable that was not defined in dbt_project.yml and was not passed via the --vars flag, causing a compilation error.

Common causes

1A new model was added using var() but the variable was not added to the vars section of dbt_project.yml
2The variable was defined in a package's dbt_project.yml but the consuming project does not define it, and no default is provided
3The variable name in the var() call has a typo compared to the key in dbt_project.yml
4A --vars override in a CI/CD job specifies a different variable name than what the model expects

How to fix it

1Step 1: Identify the variable name from the compilation error message.
2Step 2: Add the variable to the vars section of dbt_project.yml with a sensible default value.
3Step 3: Alternatively, provide a default directly in the code: var('my_var', 'default_value').
4Step 4: If the variable should differ per environment, configure it as a dbt Cloud environment variable using env_var() or via the --vars flag in the job definition.
5Step 5: Run 'dbt compile' to confirm the variable resolves correctly.

Frequently asked questions

What is the variable resolution order in dbt?

dbt resolves var() in this order: 1) --vars passed at command-line invocation, 2) variables defined in the root project's dbt_project.yml, 3) variables defined in the package's own dbt_project.yml. The first match wins.

Can I use dbt project variables to set schema names per environment?

Yes. A common pattern is to define a target_schema var in dbt_project.yml with a default, then override it per environment using the --vars flag in dbt Cloud job definitions. This is simpler than using full custom schema macros for basic environment separation.