{"record":{"id":"f4453b971e66fdc8","repo":"Unity-Technologies/UnityCsReference","slug":"unpackprefabinstance-must-be-called-with-a-root-pr","errorCode":null,"errorMessage":"UnpackPrefabInstance must be called with a root Prefab instance GameObject.","messagePattern":"UnpackPrefabInstance must be called with a root Prefab instance GameObject\\.","errorType":"validation","errorClass":"ArgumentException","httpStatus":null,"severity":"error","filePath":"Editor/Mono/Prefabs/PrefabUtility.cs","lineNumber":2771,"sourceCode":"\n            prefabInstanceReverted?.Invoke(instanceRoot);\n        }\n\n        [AutoStaticsCleanupOnCodeReload]\n        public static event Action<GameObject, PrefabUnpackMode> prefabInstanceUnpacking;\n        [AutoStaticsCleanupOnCodeReload]\n        public static event Action<GameObject, PrefabUnpackMode> prefabInstanceUnpacked;\n\n        public static void UnpackPrefabInstance(GameObject instanceRoot, PrefabUnpackMode unpackMode, InteractionMode action)\n        {\n            if (instanceRoot == null)\n                throw new ArgumentNullException(nameof(instanceRoot));\n\n            if (!IsPartOfNonAssetPrefabInstance(instanceRoot))\n                throw new ArgumentException(\"UnpackPrefabInstance must be called with a Prefab instance.\");\n\n            if (!IsOutermostPrefabInstanceRoot(instanceRoot))\n                throw new ArgumentException(\"UnpackPrefabInstance must be called with a root Prefab instance GameObject.\");\n\n            if (action == InteractionMode.UserAction)\n            {\n                var undoActionName = \"Unpack Prefab instance\";\n                Undo.RegisterFullObjectHierarchyUndo(instanceRoot, undoActionName);\n                var newInstanceRoots = UnpackPrefabInstanceAndReturnNewOutermostRoots(instanceRoot, unpackMode);\n                foreach (var newInstanceRoot in newInstanceRoots)\n                {\n                    var prefabInstance = PrefabUtility.GetPrefabInstanceHandle(newInstanceRoot);\n                    if (prefabInstance)\n                    {\n                        Undo.RegisterCreatedObjectUndo(prefabInstance, undoActionName);\n                    }\n                }\n            }\n            else\n            {\n                UnpackPrefabInstanceAndReturnNewOutermostRoots(instanceRoot, unpackMode);","sourceCodeStart":2753,"sourceCodeEnd":2789,"githubUrl":"https://github.com/Unity-Technologies/UnityCsReference/blob/225b0fbdb57cc17d094e8056b71f8314aba56f73/Editor/Mono/Prefabs/PrefabUtility.cs#L2753-L2789","documentation":"PrefabUtility.UnpackPrefabInstance throws an ArgumentException when instanceRoot is not the outermost root of a prefab instance. The method only accepts the top-level GameObject of a prefab instance, not nested children inside one.","triggerScenarios":"Calling UnpackPrefabInstance with a child GameObject inside a prefab instance rather than the instance root. Also occurs when multiple nested prefab instances exist and you pass an inner instance root instead of the outermost one.","commonSituations":"Developer selected a nested prefab instance child, or iterated the hierarchy and passed a deep child rather than finding the outermost root. Common with nested prefabs introduced in Unity 2018.3+.","solutions":["Find the outermost root first: var root = PrefabUtility.GetOutermostInstanceRoot(go) and pass that.","Use PrefabUtility.IsOutermostPrefabInstanceRoot(go) to verify before unpacking.","When processing from child references, walk up: while (go.transform.parent != null && IsPartOfNonAssetPrefabInstance(go.transform.parent.gameObject)) go = go.transform.parent.gameObject."],"exampleFix":"// before\nPrefabUtility.UnpackPrefabInstance(nestedChildGo, PrefabUnpackMode.OutermostRoot, InteractionMode.UserAction);\n// after\nvar root = PrefabUtility.GetOutermostInstanceRoot(go);\nif (root != null)\n    PrefabUtility.UnpackPrefabInstance(root, PrefabUnpackMode.OutermostRoot, InteractionMode.UserAction);","handlingStrategy":"validation","validationCode":"var root = PrefabUtility.GetOutermostInstanceRoot(go);\nif (root != null)\n    PrefabUtility.UnpackPrefabInstance(root, mode, action);","typeGuard":"static bool IsOuterRoot(GameObject go) => go != null && PrefabUtility.IsOutermostPrefabInstanceRoot(go);","tryCatchPattern":null,"preventionTips":["Use GetOutermostInstanceRoot to resolve the correct root for nested prefabs","Test with nested prefab hierarchies during development","Avoid assuming a child GameObject is an instance root"],"tags":["unity","prefab","nested-prefab","argument-validation","editor"],"backgroundTag":null,"analyzedSha":"225b0fbdb57cc17d094e8056b71f8314aba56f73","analyzedAt":"2026-08-13T19:07:19.849Z","schemaVersion":2},"datasetVersion":"2026-08-13T19:17:28.613Z"}