fix agent hallucinated a source table that isn't in sources.yml: config error
Teaches a fix agent to verify source tables against declared sources with dbt ls before referencing them, and to add genuinely missing sources to sources.yml. Use when an agent references a source table that is not declared. Not for sources that are declared but misconfigured.
TL;DR
The agent referenced a source table that was never declared. Before using any source() call, verify it with dbt ls --resource-type source. If the table genuinely exists in the warehouse but is undeclared, add it to _sources.yml; if the agent invented it, correct the reference.
Error
fix agent hallucinated a source table that isn't in sources.yml: config errorSteps
- Verify the claim:
dbt ls --resource-type source --select source:[NAME].[TABLE]. Expected: either it exists or the hallucination is confirmed. - If it does not exist, check the warehouse: does the table really exist there? Expected: you distinguish "undeclared but real" from "invented".
- If real but undeclared, add it to
_sources.ymlwith the correct database, schema, and table. Expected: the declaration matches the warehouse. - If invented, find the real source the agent meant (list sources, match by intent). Expected: a verified, declared source.
- Run
dbt parseand continue with the verified reference. Expected: no undeclared sources remain.
When to use
- An agent's
source()reference fails because the source was never declared. - Any agent-generated source reference.
When not to use
- The source is declared but the config is wrong (fix the declaration).
- A human wrote the reference (verify it the same way, but it is not a hallucination).
Tool compatibility
- dbt Core 1.0 and later, all adapters.
Variant phrasings
Agent added a model ref instead of a source
Related confusion: raw tables are sources, not models; declare them as sources.
sources.yml exists but the agent did not read it
Always list declared sources before inventing new ones.
Why it happens
Agents pattern-match source('raw', 'orders') from examples and assume the table exists. Without checking the project's actual declarations, the reference is a guess, and dbt fails on the undeclared source.
Edge cases
- The
_sources.ymlfile must be under a parsed path, or declarations are invisible. - Table names are case-sensitive on some warehouses; verify the exact spelling.
- Document the new source's owner and freshness expectations when adding it.
Provenance
Resolved from the public thread: https://vectle.com/posts/pstmtR1QWRurAIar5ktetnLg