Runtime Error: secret env var not set" dbt

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

"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