Godot 4 generates a UID per resource for stable references that survive renames/moves. Scenes use uid://... URIs internally. The .uid file stores the mapping; the resource file embeds the same UID.

Why do merge conflicts happen?

Two devs add similar files; Godot assigns different UIDs locally. On merge, .uid files conflict, and references in scenes point to different UIDs than the file claims.

For conflicting .uid: keep one version, delete the other. Godot rescans on next editor open and re-imports. For broken scene references, open and re-link the resource in the inspector.

Fix: Godot Resource UID Mismatch After Merge

Quick answer: Resolve the .uid conflict (keep either side), delete the other, restart Godot to re-import. If scenes lost references, open them and re-link missing resources in the Inspector.

Two devs add player_skin.png on separate branches. Merge succeeds but Godot reports “resource not found” in scenes referencing it. The two branches assigned different UIDs to the “same” file.

How UIDs Work

Each resource has a uid:// URI inside the project. Scenes and other resources reference by UID, not path. The .uid file maps UID → path. Conflict = ambiguous mapping.

Spot the Conflict

git status
> both modified: assets/player_skin.png.uid

Or the .import file in some versions. Either side’s UID is fine if you remap referencing scenes; but pick one to avoid confusion.

Resolution Steps

Pick one UID (use whichever ours/theirs has wider downstream impact).
git checkout --theirs assets/player_skin.png.uid (or ours).
git add the resolved file.
Open Godot — it scans and re-imports any orphaned resources.
Open referencing scenes; if a placeholder appears, re-link to the resource.

Prevent Future Conflicts

Avoid creating “the same asset” on parallel branches. If unavoidable:

Coordinate via PR comments before creating duplicates.
Or have one dev create the asset (gets a UID), the other rebases on top.

Git Attributes Trick

For .uid files specifically, configure git to always prefer one side (say, ours):

# .gitattributes
*.uid merge=ours

Mark them as binary-with-ours strategy; merge auto-resolves. Then Godot re-syncs on launch. Cuts down on merge friction.

Verifying

Open project, check all scenes referencing the resource. No “missing” placeholders. Play game; texture loads correctly. Both authors’ intended changes preserved.

“UID conflicts are a sign of parallel asset creation. Coordinate or use git attributes to make merges painless.”

For team projects, commit .uid files to source control — otherwise UIDs regenerate per machine and break scene references.