Fix: Godot Scene Instance References Broken After Rename

You renamed player.tscn to character.tscn using your file explorer, opened Godot, and now half the levels in the project show red error icons where the player instance used to be. The Inspector says “Cannot load resource at path: res://player.tscn”. Worse, some instances show the right icon but instantiate as the wrong type at runtime.

Why External Renames Break References

Godot 4 stores resource references in two forms inside .tscn files:

• Path: [ext_resource path="res://player.tscn"] — a literal string.
• UID: [ext_resource uid="uid://abc123" type="PackedScene"] — a stable identifier resolved via .uid files.

When you rename via the FileSystem dock, Godot rewrites every other file that references it, updating both paths and UIDs. The .uid sidecar file is moved alongside the renamed resource. External renames skip all of this. The path stops resolving and the UID points at the still-existing-but-orphaned .uid file that no longer matches the resource’s new location.

Step 1: Use the FileSystem Dock

If the rename hasn’t happened yet:

1. Open the Godot editor.
2. Locate the file in the FileSystem dock (bottom-left by default).
3. Right-click → Rename (or select and press F2).
4. Type the new name. Godot rewrites references across the project before the rename completes.

This is the only sanctioned way to rename. It works for scenes, scripts, shaders, and any other res:// asset.

Step 2: If Already Renamed Externally — Revert and Retry

Use git to undo:

git mv character.tscn player.tscn
git mv character.tscn.uid player.tscn.uid # if it exists
git restore --staged --worktree .

Then open Godot, let it reimport, and use the FileSystem dock’s rename action. Done.

Step 3: If You Can’t Revert — Manual Repair

If the rename is committed and you must move forward, find every reference and update it:

# Find every reference to the old path
grep -rln "res://player.tscn" .

# Replace with the new path across the project
grep -rl "res://player.tscn" . | xargs sed -i "s|res://player.tscn|res://character.tscn|g"

For UIDs, generate a new one for the renamed file:

# With the editor closed
godot --headless --import .

Godot scans the project and produces fresh .uid files for any resource missing one. Open the project, save each affected scene, and commit.

Step 4: Update Any String-Based load() Calls

The FileSystem dock rewrites resource references inside .tscn and .tres files. It does not rewrite string literals in your scripts:

# BROKEN after renaming player.tscn to character.tscn
var player_scene = load("res://player.tscn")

# Use preload with a uid for safety
var player_scene = preload("uid://abc123")

Using preload() with a UID rather than a path makes future renames non-breaking — the UID stays stable across renames.

Verifying

Run Project → Tools → Reload Current Project. Watch the editor’s output panel for “Cannot load” errors. Open each affected scene and confirm instances appear correctly. Run the game and trigger every code path that instantiates a renamed scene — runtime errors look like ERROR: Resource file not found: res://player.tscn.

“If a file lives in res://, rename it inside the editor. The shortcut of using your file manager costs you an afternoon of broken references.”

Prefer uid:// over res:// in new code — renaming becomes a no-op.