agent applied the ref fix to the wrong schema.yml file

TL;DR

Large projects split schema.yml by folder, and an agent edited the copy that does not govern the failing model, so nothing changed. Find the YAML that actually defines the model (the one in its folder or referenced by its patch), move the fix there, and revert the stray edit. Verify by parsing and checking the manifest description of the model.

agent applied the ref fix to the wrong schema.yml file

Use this when

• an agent reported fixing a ref or test in schema.yml but dbt shows the same error
• the project has multiple schema.yml or _models.yml files with overlapping content
• the model appears in the manifest with the old configuration despite the edit

Not for this skill when

• the agent edited the right YAML but the YAML has a syntax error elsewhere, fix the syntax
• the fix needed is in model SQL, not YAML at all
• two YAML files both define the model, that duplicate definition is its own error to clean up first

Steps

1. Locate every YAML mention of the model: grep the models tree for the model name under models: entries. List each file and the folder it sits in relative to the model SQL file. Verify: you have all YAML files that mention the model.

2. Determine the governing file: dbt attaches YAML properties from the file in the model folder (or the patch path in dbtproject.yml). Open target/manifest.json and check the model patchpath to see which file dbt actually used. Verify: manifest patch_path names the authoritative YAML file.

3. Move the agent fix into that file with the same content, and revert the edit in the wrong file (restore it from version control if it was the only change there). Verify: the fix exists only in the governing YAML and the stray edit is gone.

4. Run dbt parse, then dbt ls --select for the model and a compile, confirming the new config (test, description, or ref-related property) is in effect. Verify: parse succeeds and the manifest reflects the fix for the model.

Variant phrasings

agent created a new schema.yml instead of editing

A fresh file in the wrong folder looks plausible and parses, but its entries may attach to nothing or duplicate existing entries. Delete the orphan file after moving its content.

monorepo with several dbt projects

The same model name can exist in two projects. Confirm the project root the failing command runs from before moving any edits.

Compatibility: dbt-core YAML properties and patch paths (manifest patch_path field); projects commonly split schema files per folder under models/.

Why it happens

dbt binds YAML properties to models by name plus patch path resolution, and large projects accumulate similarly named schema files across folders and refactors. An edit to a non-governing file is syntactically valid and silently inert, so the agent sees a clean diff while dbt keeps using the old definition. Only the manifest shows which file actually governed.

Edge cases / pitfalls

• Duplicate model entries across YAML files produce their own parsing warnings; clean duplicates when you find them, do not leave both.
• Renaming YAML files is safe for dbt but breaks agent habits; document the schema file convention in the project readme.
• Always verify agent YAML edits via the manifest, not via the diff alone.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_i7t3IlztPfhaFbmv2vXmiQ