dbt compilation error: env_var not found

TL;DR

dbt resolves env_var at parse time from the environment of the process that launched dbt. Not found means that process never had the variable: it was set in a different shell, exported after dbt started, or missing from the CI environment. Export it where dbt launches, or give the call a safe default. The variable existing on your laptop proves nothing about the CI runner.

dbt compilation error: env_var not found

Use this when

• dbt compile or run fails with env_var not found.
• It works locally but fails in CI or dbt Cloud.
• A new variable was added and old environments do not have it.

Not for this skill when

• The variable resolves but the value is wrong. Check the value at the source.
• You need per-run dynamic values. env_var is parse-time only.

Steps

1. Read the error for the exact variable name. Note the name, including case. Verify: the missing variable is named
2. Check the launching environment: echo the variable in the same shell or CI step that runs dbt. Note whether it is actually set there. Verify: the real environment is inspected
3. Add the variable to the CI environment, the dbt Cloud environment settings, or the wrapper script that launches dbt. Note the launch path now carries it. Verify: the launch path is fixed
4. Where a missing variable should not be fatal, add a default: env_var('NAME', 'fallback'). Note parsing no longer depends on the variable existing. Verify: the fragile reference is hardened
5. Re-run dbt compile and confirm parsing succeeds. Note the error is gone. Verify: the fix is verified

Variant phrasings

dbt env_var default value

The hardening-shaped search.

dbt cloud environment variables missing

The CI-shaped phrasing.

Compatibility: dbt Core 1.x and dbt Cloud. Parse-time resolution is identical everywhere; where you set the variable differs.

Why it happens

Jinja rendering happens before dbt does anything else, in the process you started. There is no second chance to inject the variable later, and no lookup in other shells, other CI steps, or the dbt Cloud UI unless you put it there. The error names the variable precisely because the fix is always about the launching environment. Teams hit this on every new CI pipeline and every new variable because local shells accumulate exports that CI runners never had.

Edge cases / pitfalls

• A default that silently papers over a missing production secret is dangerous. Use defaults for non-sensitive config, never for credentials.
• dbt Cloud job environment variables override the environment-level ones. Check both when a value looks wrong.
• Sourcing a .env file in one CI step does not carry it to the next step unless the CI system persists env across steps.
• Variable names with typos fail the same way as missing variables. Copy the name from the error, not from memory.

Provenance

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

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

Thread query: dbt compilation error: env_var not found

TL;DR: dbt resolves env_var at parse time from the environment of the process that launched dbt. Not found means that process never had the variable: it was set in a different shell, exported after dbt started, or missing from the CI environment. Export it where dbt launches, or give the call a safe default. The variable existing on your laptop proves nothing about the CI runner.