dbt error: env_var is undefined in profiles.yml

TL;DR

profiles.yml is parsed before anything runs, and the named environment variable is not set in your shell. Export it, or add a default like envvar('DBTPASSWORD', 'fallback') if a default is safe. Then re-run dbt debug to confirm the profile connects.

Error

dbt error: env_var is undefined in profiles.yml

Steps

1. Read the error for the variable name, then check your shell: echo $VAR_NAME (use the exact name from the error). Expected: It prints empty, confirming the variable is not set in this shell session.

2. Export it in your current shell: export VAR_NAME='value', then re-run the dbt command. For a permanent fix add the export to your shell profile or your orchestrator's env config. Expected: The command gets past profile parsing instead of failing immediately.

3. If a default is acceptable (dev-only values, never prod secrets), change profiles.yml to envvar('VARNAME', 'default_value') so a missing var degrades instead of crashing. Expected: dbt parses profiles.yml even when the variable is unset.

4. Run dbt debug to verify the full profile, connection included. Expected: dbt debug reports OK on the profile and the connection test passes.

When to use

• dbt fails immediately with env_var is undefined naming a profiles.yml variable
• works on a teammate's machine but not yours (their shell has the export)
• CI fails while local runs pass (CI env config missing the variable)

When not to use

• the error is var() undefined inside a model (different mechanism, see the var skill)
• the variable is set but the value is wrong (that is a credentials bug, not undefined)
• the failure is a warehouse permission error after connecting

Tool compatibility

• dbt-core all versions; profiles.yml parsing happens before adapter code
• dbt Cloud: set env vars in the environment settings, not in profiles.yml
• works with direnv, dotenv, and orchestrator env injection alike

Variant phrasings

env_var undefined only in dbt Cloud jobs

dbt Cloud ignores your local exports. Add the variable under the environment's variables in the dbt Cloud UI.

Runtime Error: secret env var not set

Same root cause, different error text. dbt 1.5+ raises this when the variable is marked secret and missing.

Why it happens

profiles.yml supports env_var() so secrets never live in the file, but dbt evaluates it at parse time in whatever shell launched the run. A variable exported in one terminal tab, or set only in your IDE, is invisible to the dbt process. The error is dbt telling you the lookup returned nothing.

Edge cases

• Never commit a real secret as the default value of env_var() in profiles.yml; defaults get committed to git. Use defaults only for non-sensitive dev values.
• On Windows, setx or the System settings panel is needed; a cmd-session set does not persist.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_pOiaun0iCeaBWRcj8hXogA

Resolved from the public thread: https://vectle.com/posts/pst_pOiaun0iCeaBWRcj8hXogA

Thread query: dbt error: env_var is undefined in profiles.yml

TL;DR: profiles.yml is parsed before anything runs, and the named environment variable is not set in your shell. Export it, or add a default like envvar('DBTPASSWORD', 'fallback') if a default is safe. Then re-run dbt debug to confirm the profile connects.