Unity Prefab Guide
Unity Nested Prefabs Explained: Overrides, References, and Merge Conflicts
An explanation of nested prefab ownership, overrides, references, and the merge conflicts these relationships can create.
A mental model for nested prefabs
Nested prefabs are powerful because they let teams compose reusable prefab assets. They are risky in review because one visible change can involve several layers of ownership: the outer prefab, the nested prefab, local overrides, source-prefab references, and serialized YAML identity.
Think of a nested prefab as two relationships at the same time:
- It belongs to the outer prefab structure.
- It still points back to its own source prefab asset.
That means a reviewer cannot inspect only the local YAML lines. They need to know whether the change belongs to the outer prefab, the nested prefab source, an instance override, a prefab variant layer, or a reference between those layers.
How nested prefabs interact with overrides
Nested prefabs often appear in review because somebody added a prefab instance inside another prefab or changed a property on a nested object. Unity can treat these as overrides depending on where the edit was made and whether the change has been applied to the outer prefab asset.
The practical risk is that "apply this override" is not always a simple idea. In multi-level prefab setups, the team may need to choose whether a change belongs to the nested prefab source, the outer prefab, or a local instance.
Raw YAML signals reviewers should recognize
Nested prefab changes often surface as PrefabInstance, m_Modification, source prefab references, stripped objects, and GUID/fileID pairs. A simplified YAML fragment can look like this:
--- !u!1001 &9900112233
PrefabInstance:
m_SourcePrefab: {fileID: 100100000, guid: a1b2c3d4..., type: 3}
m_Modification:
m_Modifications:
- target: {fileID: 4455667788, guid: a1b2c3d4..., type: 3}
propertyPath: m_Name
value: Door_Blue
As Unity meaning, that might be: the outer prefab contains a nested door prefab, and this instance overrides the nested door's name or property. The important review question is not "did a YAML value change?" It is "which prefab layer owns this override, and should this local difference survive the merge?"
Why nested prefab merge conflicts are risky
Nested prefab conflicts become risky when branches change different layers of the same relationship. Common examples:
- One branch edits the nested prefab source while another branch edits an override on an outer prefab instance.
- One branch adds a nested prefab while another branch changes sibling order or parent hierarchy.
- One branch changes a reference inside the nested prefab while another branch replaces the referenced asset.
- One branch applies an override to the outer prefab while another branch keeps it as a local instance override.
- One branch removes a nested object while another branch edits a component on that object.
These conflicts are not equal. Some are ordinary property conflicts. Some are ownership conflicts. Some are reference integrity conflicts. Treating all of them as line conflicts hides the decision the reviewer actually needs to make.
Nested prefab review checklist
Before accepting a nested prefab change, check:
- Which prefab asset is the source of the nested instance?
- Was the nested prefab added as an override or applied into the outer prefab asset?
- Which object path and component path changed?
- Did the change alter a reference, GUID, fileID, material, script, or prefab source?
- Does the same change need to live in the nested source prefab, the outer prefab, or a local instance?
- Did the merge create missing scripts, dangling references, or stale overrides?
FAQ
What are Unity nested prefabs?
Unity nested prefabs are prefab instances placed inside other prefab assets. The nested prefab keeps its link to its own prefab asset while also forming part of the outer prefab asset.
Why are nested prefabs hard to merge?
Nested prefabs are hard to merge because changes can affect the outer prefab, the nested prefab source, local overrides, references, and apply targets at the same time.
How are nested prefabs related to prefab overrides?
A nested prefab can be added as an override to an outer prefab instance, and overrides can exist at multiple levels when nested prefabs or prefab variants are involved.
What should reviewers check when nested prefabs change?
Reviewers should check which prefab layer changed, which override target is affected, whether references still point to the intended assets, and whether the merge changed source-prefab or nested-instance ownership.
Try MergeSight
Review the Unity change, not the YAML noise
Use MergeSight to see nested prefab sources, local overrides, object identity, and references together during review or merge.