## TL;DR

dbt calls `env_var('SECRET_NAME')` with no default, and the variable is not set in the environment running dbt. Export the variable before running, add a default like `{{ env_var('SECRET_NAME', 'fallback') }}`, or set it in dbt Cloud's environment variables. Then rerun.

## Error

```text
"Runtime Error: secret env var not set" dbt
```

## Steps

1. Find the `env_var` call named in the error (the traceback gives the file and line). Expected: you know exactly which variable dbt wants.
2. Check whether it is set in the current shell: `printenv SECRET_NAME`. Expected: empty output confirms it is unset.
3. Export it in the shell that runs dbt, or add it to the CI job's environment variables. Expected: `printenv` now shows a value.
4. Alternatively, give the call a default so local runs work without the secret value `{{ env_var('SECRET_NAME', 'dev-fallback') }}`. Expected: dbt no longer errors when the variable is missing.
5. Run `dbt debug`, then the failing command. Expected: the runtime error is gone.

## When to use

- dbt fails with "secret env var not set" or "required env var not set".
- A teammate's run works but yours does not (their shell has the variable).

## When not to use

- The variable is set but holds the wrong value (fix the value, not the lookup).
- You are on dbt Cloud (set the variable in Environment Settings instead of the shell).

## Tool compatibility

- dbt Core 1.0 and later, all adapters. `env_var` with a default argument is supported everywhere.

## Variant phrasings

### Env var 'X' is not set and no default was provided

The long form of the same error; the fix is identical.

### Secret env var works locally but not in CI

The CI job environment is missing the variable; add it to the job configuration.

## Why it happens

`env_var('NAME')` without a second argument is a hard requirement. dbt raises at runtime when the process environment lacks the variable, which commonly happens when switching shells, machines, or CI jobs.

## Edge cases

- Defaults are fine for non-sensitive values; never put a real secret as a default in committed code.
- dbt Cloud environment variables support per-environment scoping; set prod secrets only on prod.
- Shell profiles that export variables do not apply to non-interactive CI shells; set them in the job definition.

## Provenance

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