## 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 env_var('DBT_PASSWORD', 'fallback') if a default is safe. Then re-run dbt debug to confirm the profile connects.

## Error

```text
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 env_var('VAR_NAME', '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