agent renamed the model file but missed a downstream ref()

TL;DR

Renaming the .sql file renames the model, but every ref('old_name') downstream still points at the old name and compilation fails with a depends-on-missing-node error. Either rename back, or update all refs to the new name and recompile the whole downstream graph. Use dbt rename-aware search (grep for the old name across all file types) so YAML, tests, and exposures are caught too.

agent renamed the model file but missed a downstream ref()

Use this when

• after a model file rename, dbt compile fails saying a model depends on a node named with the old name that was not found
• an agent renamed a file via the filesystem instead of a refactor that updates refs
• the old name still appears in ref calls, YAML docs, or exposures

Not for this skill when

• the model was deleted on purpose and downstream models should be deleted or repointed as a design change
• the missing node is a source, not a model, fix the source definition
• two models now share the new name, resolve the duplicate first

Steps

1. Inventory the old name: grep the entire project for the old model name across .sql, .yml, and .md files, including ref calls, model lists, and exposure depends_on entries. Verify: every textual reference to the old name is listed.

2. Decide direction: if the rename was intentional and approved, update each reference to the new name; if it was an agent accident, rename the file back to the original name and discard reference edits. Verify: one consistent name is chosen for the model everywhere.

3. Apply the changes, then run dbt parse and dbt ls to confirm the model exists under the chosen name with its full downstream graph intact. Verify: parse succeeds and the model shows the expected children in dbt ls output.

4. Compile the downstream chain with dbt compile --select using the model name with a trailing plus to include children, and run its tests. Verify: the downstream graph compiles and tests pass.

Variant phrasings

rename also changed the folder

Moving folders can drop folder-level config (materialization, tags, schema) from dbt_project.yml. Reapply config for the new path in the same change.

versioned model rename

Renaming a versioned model touches its version YAML entries as well; update the model name and keep versions mapping consistent.

Compatibility: dbt-core model naming by filename and ref resolution across SQL and YAML. Applies to core projects and dbt Cloud IDE renames alike.

Why it happens

dbt binds model identity to the filename at parse time, while references bind by the name string at compile time. A filesystem rename updates the first binding and none of the second, so the project contains pointers to a node that no longer exists. The compiler error is precise; the miss is purely that rename and reference updates were not done as one atomic change.

Edge cases / pitfalls

• git mv preserves history for the renamed file; plain moves lose blame history and make the change harder to review.
• A select string or saved query in BI tools may hardcode the old table name outside dbt; renaming the model renames the built table too, so warn downstream owners.
• If the built relation name must stay stable through a file rename, set an explicit alias or database/schema config to decouple them.

Provenance

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