What causes DbtVariableUndefinedError?

The variable is referenced in a model but is missing from the vars block in dbt_project.yml. The variable was passed with --vars on the command line locally but not set in the dbt Cloud job definition. The variable name contains a typo or uses a different casing than defined. A package macro uses a variable that requires a project-level definition not included in the project

How do I fix DbtVariableUndefinedError?

Step 1: Add the variable with a default value in dbt_project.yml: vars: my_variable: 'default_value'.. Step 2: Use var('my_variable', 'fallback') in models and macros to provide a runtime fallback and avoid hard failures.. Step 3: For dbt Cloud jobs, add the variable in the job configuration under Environment Variables or --vars in the command.. Step 4: Search all models and macros for var(' calls to map all undefined variables and add them to dbt_project.yml.. Step 5: Run dbt compile to verify all variables resolve before executing the pipeline.

High severitycompilation

Power BI Refresh Error:
DbtVariableUndefinedError

What does this error mean?

A dbt model or macro references a variable with var('name') that was not defined in dbt_project.yml or passed on the command line, causing the run to fail with an undefined variable error.

Common causes

1The variable is referenced in a model but is missing from the vars block in dbt_project.yml
2The variable was passed with --vars on the command line locally but not set in the dbt Cloud job definition
3The variable name contains a typo or uses a different casing than defined
4A package macro uses a variable that requires a project-level definition not included in the project

How to fix it

1Step 1: Add the variable with a default value in dbt_project.yml: vars: my_variable: 'default_value'.
2Step 2: Use var('my_variable', 'fallback') in models and macros to provide a runtime fallback and avoid hard failures.
3Step 3: For dbt Cloud jobs, add the variable in the job configuration under Environment Variables or --vars in the command.
4Step 4: Search all models and macros for var(' calls to map all undefined variables and add them to dbt_project.yml.
5Step 5: Run dbt compile to verify all variables resolve before executing the pipeline.

Frequently asked questions

What is the difference between var() and env_var() in dbt?

var() reads from dbt_project.yml or --vars at runtime; env_var() reads from environment variables in the shell or dbt Cloud environment settings. Use env_var() for secrets and environment-specific values, var() for project-wide configuration.

Can I override a dbt variable for a single model without changing dbt_project.yml?

Yes — pass --vars '{"my_variable": "new_value"}' on the command line, or use a dbt Cloud job configuration override. The command-line value takes precedence over dbt_project.yml.