Quick answer: Moving Godot resource files via the OS file manager breaks all references that used UIDs? The editor maintains a UID-to-path cache that doesn’t auto-update for external moves.

A designer reorganizes art folders in Finder. Every scene referencing those textures shows missing-resource warnings on open.

Always Move via FileSystem Dock

The editor’s FileSystem dock’s move handles UID cache updates plus updates references in scenes / scripts. OS-level moves bypass this.

Rebuild UID Cache

If you moved files outside the editor, delete .godot/uid_cache.bin and reopen the project. Godot rebuilds the cache by scanning. Existing UID-based references may still break.

Path-Based vs UID

Older projects use path references (res://art/foo.png). Newer projects prefer UIDs (uid://abc123). Path references survive OS moves but rename to a different file path; UIDs survive renames but not OS-level changes.

Version Control

Always commit before reorganizing. If the move corrupts references, revert and try via the editor.

Verifying

After file moves, all references resolve. No missing-resource warnings.

“Move resources via the editor. OS-level moves break UID-based references.”

Establish a project rule: never move resource files outside the editor. Saves catastrophic re-linking sessions later.