Compilation Error: var is undefined in dbt model

TL;DR

The var was never defined, so dbt has nothing to substitute. Define it in dbtproject.yml under vars, pass it with --vars on the command line, or give the var() call a default like var('myvar', 'fallback'). Pick one; the default argument is the quickest unbreak.

Error

Compilation Error: var is undefined in dbt model

Steps

1. Find the var call in your model: search for var('name') matching the undefined name in the error. Expected: You locate the exact line and the var name dbt complains about.

2. Check dbt_project.yml for a vars: block defining it, and check whether your run passes --vars '{name: value}'. One of these is missing. Expected: You confirm the var is defined nowhere, or only defined for a different target.

3. Fix it: add it under vars: in dbtproject.yml, or change the call to var('name', 'sanedefault') so it degrades gracefully. Expected: The var resolves; you can verify with dbt compile and inspect the rendered SQL in target/compiled.

4. Run dbt compile --select the model, then a full dbt compile to catch other models using the same var. Expected: Whole project compiles with no undefined-var errors.

When to use

• Compilation Error names a var as undefined
• a model works for one target but fails for another (vars differ per target)
• a new model copied a var() call from elsewhere without the definition

When not to use

• the error is about env_var, not var (that is an environment variable, different fix)
• the var is defined but has the wrong value (that is a config bug, not undefined)
• the failure happens at warehouse runtime, after successful compile

Tool compatibility

• dbt-core 1.0 and later; --vars CLI flag syntax unchanged
• dbt Cloud: set vars in the job's deployment environment or job settings
• dbt_project.yml vars block works across all adapters

Variant phrasings

var is undefined only in CI

CI runs dbt without the --vars flag your local alias includes. Put the var in dbt_project.yml instead of relying on local shell aliases.

var undefined inside a macro

Same fix, but check the macro is not called before vars load. Macro-level var() calls resolve fine as long as the var is defined project-wide.

Why it happens

var() is dbt's project-level variable lookup. If the name is not in dbt_project.yml vars and not passed via --vars, there is nothing to return and dbt raises at compile time rather than rendering an empty string. Copy-paste between projects is the usual way the definition gets lost.

Edge cases

• vars: defined under a target-specific block only apply to that target; a model compiled for prod will not see dev-only vars.
• Watch quoting: --vars '{my_var: abc}' needs the braces quoted or the shell eats them.

Provenance

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