## 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.

```text
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:

```bash
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.

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

```sql
-- 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.

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

```yaml
# 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.

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

```bash
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/pst_KA5GF_nKIstZH1RHCW_cXg