dbt Compilation Error: model not found

TL;DR

dbt cant resolve a ref() because no model with that name exists in the project: it was renamed, deleted, lives in a disabled path, or the ref has a typo. List models with dbt ls, fix the ref to match the real filename-derived name, and check dbt_project.yml model paths.

dbt Compilation Error: model not found

Use this when

• dbt compile or dbt run fails with model not found
• An agent wrote a ref to a model that doesnt exist
• The error appeared after renaming model files

Not for this skill when

• The database rejects the query (thats permissions or the warehouse)
• Jinja itself fails to parse (thats a syntax error)
• A source table is stale (thats freshness)

Steps

1. List the models dbt actually knows about:

dbt ls --resource-type model | grep -i partial_name

Expected output: the real model names. If your ref target isnt listed, the name is wrong or the file isnt picked up.

1. Check the ref in the failing model against the filename:

-- broken: file is models/staging/stg_orders.sql
select * from {{ ref('stg_order') }}  -- typo: missing s

Expected output: you spot the mismatch. ref() takes the model name (filename without .sql), not the file path.

1. Verify the model file is inside a configured model path:

# dbt_project.yml
model-paths: ["models"]

Expected output: the file lives under one of these paths. Files outside model-paths are invisible to dbt no matter how correct the ref is.

1. If the model is in a package, qualify or install it:

dbt deps
dbt ls --resource-type model | grep package_model

Expected output: package models appear after dbt deps installs them. Refs to package models need the package installed, not just mentioned.

Variant phrasings

model not found after moving files into subfolders

Subfolders dont change the ref name (still the filename), but check model-paths still covers the new location.

works locally, fails in CI

CI checks out a different branch or a partial repo where the model file is missing. Diff the file lists.

Why it happens

dbt resolves ref('name') against the models it parsed from the configured paths. Anything that breaks that mapping, a typo, a rename without updating refs, a file outside model-paths, a disabled model, a missing package, produces this compile error. Agents hit it because they write refs from memory of the intended schema rather than from the actual file list.

Edge cases

• Model names must be unique across the project and installed packages; duplicates cause a different error but are worth checking.
• Disabled models (enabled: false) are invisible to refs; the error looks identical to a missing file.
• On case-sensitive filesystems, Stg_Orders.sql and stg_orders.sql differ; keep names lowercase.

Provenance

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