What causes UndefinedError: env_var?

A required environment variable (e.g. DBT_API_KEY, DBT_TARGET_SCHEMA) was not set in the CI/CD or dbt Cloud job environment. A profile.yml or dbt_project.yml uses env_var() without a fallback and the variable is only set in some environments. A new env_var() reference was added to a model or macro but the variable was not added to the deployment configuration. The environment variable was set at the OS level but not passed into the Docker container or Lambda running dbt. A typo in the variable name means the variable name in env_var() does not match the one set in the environment

How do I fix UndefinedError: env_var?

Add a default value to non-critical env_var calls: {{ env_var('MY_VAR', 'default_value') }}.. Verify the variable is set in the target environment: echo $MY_VAR or check the dbt Cloud environment variables UI.. Add the missing variable to the CI/CD pipeline secrets, dbt Cloud environment variables, or Kubernetes secrets.. Search the project for all env_var() calls without defaults: grep -r "env_var" . | grep -v ", " to find strict calls.. Use dbt debug to validate that the profile and project compile correctly with the current environment variables.

High severityconfiguration

Power BI Refresh Error:
UndefinedError: env_var

What does this error mean?

A dbt model, macro, or profile referenced an environment variable using env_var('VAR_NAME') without a default value, and the variable was not set in the execution environment. dbt raises an UndefinedError at compile time and the job fails immediately.

Common causes

1A required environment variable (e.g. DBT_API_KEY, DBT_TARGET_SCHEMA) was not set in the CI/CD or dbt Cloud job environment
2A profile.yml or dbt_project.yml uses env_var() without a fallback and the variable is only set in some environments
3A new env_var() reference was added to a model or macro but the variable was not added to the deployment configuration
4The environment variable was set at the OS level but not passed into the Docker container or Lambda running dbt
5A typo in the variable name means the variable name in env_var() does not match the one set in the environment

How to fix it

1Add a default value to non-critical env_var calls: {{ env_var('MY_VAR', 'default_value') }}.
2Verify the variable is set in the target environment: echo $MY_VAR or check the dbt Cloud environment variables UI.
3Add the missing variable to the CI/CD pipeline secrets, dbt Cloud environment variables, or Kubernetes secrets.
4Search the project for all env_var() calls without defaults: grep -r "env_var" . | grep -v ", " to find strict calls.
5Use dbt debug to validate that the profile and project compile correctly with the current environment variables.

Frequently asked questions

How do I provide a default value for env_var in dbt?

Use the two-argument form: {{ env_var('MY_VAR', 'default') }}. The second argument is returned when the variable is not set. For secrets, never provide a default — require the variable explicitly to fail fast on misconfiguration.

Can I list all environment variables used in a dbt project?

There is no built-in dbt command for this. Run grep -r 'env_var' --include='*.yml' --include='*.sql' . in the project root to find all env_var() references and their locations.