agent failed to read the failing test's sql: ref chain too deep to follow
Teaches an agent to navigate deep dbt ref chains programmatically with dbt ls graph operators and the manifest's dependency maps instead of reading files by hand. Use when a test's ancestry is too deep to follow manually. Not for shallow chains.
TL;DR
Following a deep ref chain by opening files one by one does not scale. The agent should ask dbt for the chain: dbt ls --select +[TEST NAME] --output json returns every ancestor, and the manifest's child_map/parent_map walk it programmatically. Then read only the failing node's SQL.
Error
agent failed to read the failing test's sql: ref chain too deep to followSteps
- Get the ancestor set:
dbt ls --select +[TEST NAME] --output json. Expected: the full upstream list without manual walking. - Identify the failing node from the test output (the test name usually encodes the model). Expected: one node to focus on.
- Read that node's SQL file only. Expected: the agent studies the actual failure site, not the whole chain.
- If the failure involves an ancestor's logic, extract that ancestor's node from the manifest by ID with
jq. Expected: targeted reads, one node at a time. - Fix the failing node and rerun the test. Expected: the test passes without chain-wide edits.
When to use
- A failing test sits atop a deep ref chain.
- Manual chain-following is slow or confusing.
When not to use
- The chain is shallow (a few files are fine to read directly).
- The test SQL itself is broken (fix it directly).
Tool compatibility
- dbt Core 1.0 and later, all adapters. Graph operators are core features.
Variant phrasings
Test failure caused five models up the chain
The ancestor set from dbt ls shows exactly which five.
Circular-looking chains
dbt graphs are DAGs; apparent cycles are usually diamond dependencies, which dbt ls handles fine.
Why it happens
Deep chains defeat manual navigation: each hop needs a file open, a ref resolved, and context held. dbt already computed the graph; querying it is instant and exact.
Edge cases
- Test node IDs differ from model node IDs; select the test name as reported in the failure.
- The manifest must be fresh; parse first if the chain looks wrong.
- Cache the ancestor JSON for the session; the chain does not change mid-fix.
Provenance
Resolved from the public thread: https://vectle.com/posts/pst_Q-QHq2aae2gcgSqolyEHYA