Reference Integrity Guide
Why Unity References Break: GUIDs, Meta Files, Missing Scripts, and Missing Prefabs
A guide to understanding how GUIDs, meta files, scripts, and prefab identity cause Unity references to break.
How Unity identifies referenced objects
A Unity reference breaks when its serialized identity no longer matches the target asset or object. A line diff can hide this mismatch.
Inside one YAML file, Unity identifies an object by fileID. Across assets, it combines the target asset's .meta GUID with a fileID and, when needed, a type value.
How references break after refactors or replacement
There are several common cases:
- an asset is deleted and re-added with a new meta file, which changes its GUID
- an asset is replaced with another file while identity assumptions stay tied to the old asset
- a nested or base prefab is swapped, but internal object mappings do not line up
- a script or object structure changes and dependent references are left pointing at stale targets
Why .meta files matter
If an asset's .meta GUID changes, every stored reference to the old GUID points to the wrong target or no target. Move and rename each asset with its original meta file.
Missing scripts and missing prefabs after Git merge
Typical symptoms are missing script components, missing prefab references, or warnings about a GUID Unity cannot resolve.
Common causes include:
- a script file was moved, deleted, renamed, or re-added with a different
.metaGUID - a class name or file name changed in a way that prevents Unity from loading the expected MonoBehaviour
- the project has compile errors, so Unity cannot load script types even if the serialized reference is still present
- a prefab was deleted and recreated instead of moved with its original meta file
- two branches changed the same asset identity or prefab relationship in incompatible ways
When diagnosing, search for the GUID in changed .unity, .prefab, and .asset files, then compare it with the current target asset's .meta file. If the GUID changed, the serialized reference and the current asset identity no longer agree.
Why stale references make diagnosis harder
Unity can preserve stale serialized references to avoid data loss or broad reserialization. The old data may remain until the asset is saved again or force-reserialized.
A diff can therefore mix current and stale relationship data. Verify the stored GUID and fileID against the current asset graph.
Diagnose reference problems step by step
- Check whether the target asset's GUID changed.
- Compare the old and new object identities.
- Determine whether the reference is local or cross-file.
- Look for stale data after refactors or script changes.
- Check whether nested prefab or variant ownership changed.
- List each affected reference, its current target, and any validation warning.
FAQ
Why do Unity references break after a Git merge?
Unity references can break when .meta GUIDs change, assets are deleted and re-added, or scripts stop compiling. Prefab source changes and stale fileID references can cause the same problem.
Why do missing scripts appear in Unity after merging?
Missing scripts often appear when the referenced MonoBehaviour script GUID or class identity no longer matches the serialized reference, or when compilation fails and Unity cannot load the script type.
Why does Unity show a missing prefab with a GUID?
A missing prefab with a GUID means an asset still points to an unavailable prefab identity. The prefab may be gone, have a different .meta GUID, or have been replaced without its original meta file.
Try MergeSight
Review the Unity change, not the YAML noise
Use MergeSight to trace GUID and fileID changes, identify broken targets, and review the affected Unity asset graph.