agent ref rename missed one downstream model: dag broke at 3am
Repairs incomplete agent ref renames in dbt for analytics engineers supervising repair agents. Use when a renamed ref left a stale reference that broke the DAG. Not for renames done correctly.
TL;DR
The agent renamed a model but missed a downstream ref, and the nightly run found it. Search the whole project for the old name, fix every stale ref, and compile the full project. Require full-project compile in the agent's done criteria for any rename.
Error
agent ref rename missed one downstream model: dag broke at 3amSteps
Find every stale reference: grep -rn "ref('old_name')" across the project, including macros and tests. Expected: You find the missed downstream model (and any others).
Update each stale ref to the new name. Expected: No references to the old name remain anywhere.
Run dbt compile on the full project, not just the renamed model. Expected: Full compile succeeds; the DAG is whole.
Run dbt ls to confirm the renamed model has all its downstream children attached. Expected: The DAG shows the complete downstream chain under the new name.
When to use
- a ref rename broke the DAG because one downstream was missed
- nightly run fails on a ref to a model that no longer exists under that name
- an agent renamed a model and verified only the renamed file
When not to use
- the rename was complete and verified (then something else broke)
- the missing ref is in a deleted model (that is cleanup, not a missed rename)
- the error is a different compile error
Tool compatibility
- grep for ref('old_name') across the project
- dbt compile full project to catch stragglers
- dbt ls to visualize the repaired DAG
Variant phrasings
agent renamed a source instead of a model
Same hunt, but in sources.yml and source() calls. Missed source renames break the same way.
rename missed a test's ref
Tests reference models too. The grep must cover the tests directory, not just models/.
Why it happens
Agents verify the file they edited and maybe its direct children, but ref() calls live in tests, macros, and exposures too. A rename is a project-wide operation; verifying one file is how the 3am page happens.
Edge cases
- Exposures and metrics reference models by name as well; include them in the rename checklist.
- Make full-project dbt compile a required agent done-criterion for any rename, no exceptions.
Provenance
Resolved from the public thread: https://vectle.com/posts/pst_EbgxKF85wfzfWo49X9tLfQ