dbt Node Not Found: Model Depends on Missing Ref

You renamed stg_orders to stg_orders_v2, updated one model, and ran dbt compile. The terminal answers: Model 'fct_revenue' depends on a node named 'stg_orders' which was not found. You stare at the models folder — the file is right there. Or is it? The name you see and the name dbt wants differ by one character, one folder, or one missing install.

This error is dbt's graph talking, not its SQL engine. Before dbt touches your warehouse, it builds a dependency graph from refs, sources, and packages — and compilation fails when an edge points nowhere. The SQL is usually perfect; it never even ran. Beginners debug queries for hours while the answer sits in a filename.

This guide makes the graph visible. You'll learn exactly how ref() resolves, when source() is the right call, why dbt deps matters, how case sensitivity ambushes macOS users on Linux CI, and why stale parse caches produce phantom errors. Six short sections, each ending in a command that proves the fix — and a renamed model will never ruin your morning again.

What Depends on a Node Not Found Actually Means

dbt compiles in two phases, and this error fires in phase one — graph building. dbt scans your project (plus installed packages) for models, seeds, snapshots, and sources, then resolves every {{ ref('name') }} into an edge between nodes. 'Depends on a node not found' means an edge points at nothing: the named node doesn't exist in the scanned graph. Your SQL never reaches the warehouse; the failure is pure lineage.

That framing picks your tools. Query debuggers, warehouse logs, and SQL rewrites can't help — compilation died before execution. Graph tools can: dbt ls lists resolved nodes, dbt compile reproduces the failure fast, and grep across models/ finds every caller of a renamed node. Beginners invert this and lose hours polishing queries dbt never ran.

Internalize the mental model: models/ files are nodes, ref() calls are edges, sources.yml declares the outside world, packages.yml imports foreign nodes, and target/ caches yesterday's graph. Every cause in this guide is one of those pieces disagreeing with the rest. Fix the piece, prove it with dbt ls, and compilation follows. Keep this picture handy: nodes, edges, outside world, imports, memory — five pieces, five failure modes, one ritual that checks them in order.

ref() vs source(): Picking the Right Pointer

ref() and source() answer different questions. ref('stg_orders') says 'another model in my project (or an installed package) builds this — wire my lineage, run order, tests, and docs to it.' source('ecommerce', 'raw_orders') says 'an external loader owns this table — track its freshness, don't try to build it.' Use ref() for raw tables and dbt searches its graph for a builder that doesn't exist — node not found, every time.

sources.yml is the declaration that makes source() work: source name, database, schema, table list. It buys freshness checks (source freshness jobs warn when loaders stall), documentation (raw tables appear in docs), and selection power (dbt ls --select source:ecommerce.raw_orders). None of that exists for a ref() pointed at raw — just the error.

Adopt the review rule that prevents the whole class: if dbt doesn't build it, it's a source. Staging models read sources; marts read staging refs. Any PR with ref() pointing outside models/ fails review on sight. New hires learn it once, the graph stays honest forever, and this error loses its most common cause. Make it a merge requirement and the graph stays honest no matter how fast the team grows — one review question prevents the most common compile failure beginners hit.

# sources.yml — declare the outside world once
version: 2
sources:
  - name: ecommerce
    database: analytics
    schema: raw
    tables:
      - name: raw_orders
      - name: raw_customers

-- staging model: source() for raw, ref() for dbt-built
select * from {{ source('ecommerce', 'raw_orders') }}
-- select * from {{ ref('stg_orders') }}  -- only for models YOU build

Package Deps: the Nodes You Forgot to Install

Packages extend your graph with foreign nodes — dbt_utils macros and models, dbt_expectations tests, your platform team's shared staging. But those nodes exist only after dbt deps downloads packages.yml into dbt_packages/. Reference a package model without installing and dbt reports exactly our error: the node isn't in the graph because its files aren't on disk.

The environment split makes this nasty. Your laptop has dbt_packages/ from last month's dbt deps; the fresh CI runner doesn't. Compiles pass locally, fail in CI, and the diff between environments is an untracked folder nobody diffs. Worse, unpinned versions (version: [>=1.0.0]) resolve differently per machine, so the node exists but with different columns — a subtler breakage wearing the same disguise.

Lock it down three ways: pin exact versions in packages.yml, run dbt deps as a mandatory CI step before dbt compile (not cached, not conditional), and verify with dbt ls greps that prove package nodes arrived. Treat dbt_packages/ like node_modules — gitignored, always installed fresh, never assumed present. Environment parity turns 'works on my machine' into a solved problem. Run deps even when you think nothing changed — branch switches and fresh clones are exactly when the folder goes missing.

# packages.yml — pin versions so every env resolves identically
packages:
  - package: dbt-labs/dbt_utils
    version: 1.1.1
  - package: calogica/dbt_expectations
    version: 0.10.0

# Install, then prove the nodes arrived
# dbt deps
# dbt ls --resource-type model | grep dbt_utils
# CI must run `dbt deps` BEFORE `dbt compile`, every run.

Case-Sensitive Names: the macOS-to-Linux Ambush

Filesystems disagree about case, and dbt inherits the disagreement. macOS (and Windows) default to case-insensitive disks: Orders.sql and orders.sql are the same file, so {{ ref('stg_orders') }} resolves no matter how you capitalized the filename. Linux CI is case-sensitive: the node is named by its exact filename, and a ref() off by one capital letter points nowhere. The error message even looks wrong — it names a node that appears to exist.

Renames trigger this most often: Stg_Orders.sql becomes stg_orders.sql in a cleanup PR, one caller keeps the old capital, laptop tests pass, CI burns. Verify byte-for-byte with ls piped through grep plus a grep of every ref() caller — eyeballing finds nothing because human brains normalize case automatically.

Prevent it structurally: lowercase-with-underscores for all model files, ref() strings identical to filenames, and a CI lint rejecting uppercase characters in models/ paths. The lint costs four lines of bash and ends the class permanently. Cross-platform teams should treat filename case like API contracts — exact match, machine-checked, no human judgment involved. Add the lint before your next rename PR, not after — prevention costs four lines, another incident costs an afternoon.

# Byte-for-byte check: filename vs ref() string
ls models/staging/ | grep -i orders
grep -rn "ref('stg_orders" models/ | head -20

# Enforce the convention in CI (reject uppercase model filenames)
# if ls models/ | grep -q '[A-Z]'; then echo 'UPPERCASE model file'; exit 1; fi
# Convention: lowercase_with_underscores.sql, ref() identical.

Manifest Staleness and Partial-Parse Phantoms

dbt caches aggressively for speed: target/ holds the last manifest (yesterday's graph) and partial parsing reuses it across runs. That's wonderful until you rename a model — the cache still maps the old name, the new parse half-merges, and errors describe a graph that's neither yesterday's nor today's. Phantom missing-nodes survive file checks, dep installs, and case audits because the files were never the problem.

Recognize the signature: everything on disk looks right, teammates see different errors on different machines (each cache is stale differently), and the error references names from before your rename. The cure is one clean rebuild — delete target/ and dbt_packages/, reinstall deps, compile the failing selection first (fast feedback), then prove the lineage with dbt ls --select stg_orders+ showing the node plus its downstream edges.

Make clean parses habitual around renames and branch switches, not a last resort after an hour of SQL review. Alias it if you must. And keep dbt ls in CI on every PR: graph drift then fails fast on 20-line diffs instead of detonating Friday's revenue refresh. Caches are performance tools with correctness side effects — treat them as suspects, not foundations.

# Full clean rebuild: cache is guilty until proven innocent
rm -rf target/ dbt_packages/
dbt deps
dbt compile --select fct_revenue

# Prove the edge exists before building the world
dbt ls --select stg_orders+
dbt build --select stg_orders+ --fail-fast

Debugging the Graph Step by Step

When the error hits, run the ritual in order and stop at the first red step. dbt ls on the caller proves whether the failing model itself resolves. dbt ls on the dependency with the + suffix proves the node plus its downstream edges — the single most informative command in this guide. A repo-wide grep for the ref() string finds every caller a rename missed, including the ones in marts nobody remembers. dbt compile on the narrow selection reproduces the failure in seconds instead of full-project minutes.

Each red step names its fix: caller won't resolve (fix its refs or restore its file), dependency won't resolve (typo, missing package, case mismatch, or needs source()), grep finds extra callers (update them in the same PR), compile still fails after all green (now — and only now — read the SQL). The order matters because each step is cheaper than the next, and most incidents end at step two.

Turn the ritual into pipeline: dbt compile plus dbt ls on every PR, filename lint for case, dbt deps before compile, pinned packages. Missing nodes then fail in 4 minutes on small diffs with the author watching — instead of at 5 PM on Friday with executives watching. The graph is debuggable, the ritual is five minutes, and the incident in this article becomes a story you tell, not a Friday you relive.

# The 5-minute graph debug ritual (run in order)
dbt ls --select fct_revenue          # does the caller resolve?
dbt ls --select stg_orders+          # does the dependency + children resolve?
grep -rn "ref('stg_orders')" models/  # who else points at it?
dbt compile --select fct_revenue     # reproduce fast, iterate fast

# Green across all four = graph healthy. Fix SQL next (rarely needed).