## TL;DR
dbt cannot find the model your ref() points at, so check the name character by character first. The usual suspects are a typo in ref(), a model that got disabled, or a model living in a package you did not name. Run `dbt ls` to see what dbt actually knows about, and the missing model usually reveals itself immediately.

```text
Compilation Error in model orders_summary (models/marts/orders_summary.sql)
  Model 'my_project.orders_summary' depends on a node named 'stg_ordrs' which was not found or is disabled
```

## Use this when
- compile or run fails saying a ref() target was not found or is disabled
- you renamed a model and its dependents broke
- you added a model to a package and refs cannot see it

## Not for this skill when
- the model compiles but fails at runtime, that is a SQL problem
- the missing thing is a source, check your sources yaml instead
- the error is about a macro, see the Jinja debugging skill

## Steps

1. List the models dbt actually knows about and search for your target name:

```shell
dbt ls --resource-type model --output name | grep -i stg_order
```

Expected output: the real model names dbt parsed. If your expected name is absent or spelled differently, you just found the problem.

2. Check whether the model file exists but is disabled in config, since disabled models are invisible to ref() by design:

```shell
grep -rn "enabled" models/staging/ | head -10
```

Expected output: any `enabled: false` configs. A disabled model explains the "or is disabled" half of the error message exactly.

3. Verify the ref() call itself, reading what is actually written and not what you remember writing:

```shell
grep -rn "ref(" models/marts/orders_summary.sql
```

Expected output: every ref() in the failing model. Compare each name to the step 1 output exactly, including every underscore.

4. If the model lives in an installed package, qualify the ref with the package name:

```sql
-- in models/marts/orders_summary.sql, change this:
-- {{ ref('stg_orders') }}
-- to this:
{{ ref('my_package', 'stg_orders') }}
```

Expected output: compilation succeeds. Unqualified refs only search your own project plus default resolution, so package models need the explicit qualifier.

5. Recompile from a clean parse to rule out stale artifacts hiding a model that was added recently:

```shell
dbt parse && dbt compile --select orders_summary
```

Expected output: compiled with no errors. A stale partial-parse cache can hide a model that exists on disk but never made it into the manifest.

## Variant phrasings

### dbt depends on a node named X which was not found
The full canonical message. Work steps 1 through 3 in order, it is almost always spelling or a disabled flag.

### dbt ref model not found after rename
Renames break every downstream ref() at once. Step 1 plus a repo-wide grep for the old name catches the stragglers.

### dbt model not found in package
Two packages can define the same model name, which makes unqualified refs ambiguous. Qualify with the package name as in step 4.

## Why it happens
ref() resolves against the manifest dbt builds at parse time, not against files on disk at query time. If the file is missing, disabled, misspelled, or in a package that needs qualifying, the manifest has no such node and compilation stops. The error message names both the dependent model and the missing node, which is everything you need to track it down.

## Edge cases
- model-paths config: a .sql file outside the configured model paths is never parsed. Check dbt_project.yml.
- File extension typos like .sqll are silently ignored by the parser, the file just does not exist to dbt.
- Duplicate model names across packages make unqualified refs ambiguous. Qualify them and move on.
- dbt Cloud and local CLI can parse different branches. Make sure you are compiling the branch you think you are.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_kGLhNDA6Im1u7gL-Mg7irw