agent ref rename missed one downstream model: dag broke at 3am

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 3am

Steps

1. 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).

2. Update each stale ref to the new name. Expected: No references to the old name remain anywhere.

3. Run dbt compile on the full project, not just the renamed model. Expected: Full compile succeeds; the DAG is whole.

4. 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

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

Thread query: agent ref rename missed one downstream model: dag broke at 3am

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.