dbt "Compilation Error: X is undefined" Jinja var in CI

By Kaveh Alemi·Latchkey

dbt rendered a model template and hit a Jinja name it does not know: a var() with no default and no definition, or a variable that was never set. Rendering stops because the value is undefined.

What this error means

dbt compile or run fails with "Compilation Error in model X ... 'my_var' is undefined" pointing at the template that used the variable.

Compilation Error in model daily_revenue (models/marts/daily_revenue.sql)
  'start_date' is undefined

Common causes

A var() has no default and was not passed

The model calls var('start_date') but the run did not supply it via --vars or dbt_project.yml, so it is undefined.

A variable is expected from the CI invocation

A run-scoped variable the model relies on was omitted from the dbt command in CI.

How to fix it

Supply the variable or a default

1. Pass the value with --vars in the CI command, or
2. Give var() a default so it renders without an explicit value.
3. Re-run dbt compile to confirm it renders.

dbt run --vars '{"start_date": "2024-01-01"}'

Define a project-level default

Declare the variable in dbt_project.yml or use a default in the call so CI never depends on ad hoc flags.

-- in the model
where created_at >= '{{ var("start_date", "2024-01-01") }}'

How to prevent it

• Give var() a sensible default, or pass it explicitly in CI.
• Declare shared vars in dbt_project.yml so runs are reproducible.
• Run dbt compile in CI to catch undefined variables before build.

Frequently asked questions

Related guides

References

• Python documentation
• pip documentation
• GitHub Actions documentation