{"record":{"id":"8cbd57282269876c","repo":"Unity-Technologies/UnityCsReference","slug":"unpackprefabinstance-must-be-called-with-a-prefab","errorCode":null,"errorMessage":"UnpackPrefabInstance must be called with a Prefab instance.","messagePattern":"UnpackPrefabInstance must be called with a Prefab instance\\.","errorType":"validation","errorClass":"ArgumentException","httpStatus":null,"severity":"error","filePath":"Editor/Mono/Prefabs/PrefabUtility.cs","lineNumber":2768,"sourceCode":"        internal static void Internal_CallPrefabInstanceReverted(GameObject instanceRoot)\n        {\n            Assert.IsNotNull(instanceRoot);\n\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            }","sourceCodeStart":2750,"sourceCodeEnd":2786,"githubUrl":"https://github.com/Unity-Technologies/UnityCsReference/blob/225b0fbdb57cc17d094e8056b71f8314aba56f73/Editor/Mono/Prefabs/PrefabUtility.cs#L2750-L2786","documentation":"PrefabUtility.UnpackPrefabInstance throws an ArgumentException when the provided GameObject is not part of a non-asset prefab instance. UnpackPrefabInstance only operates on prefab instances in a scene, not on prefab assets stored in the Project, and not on regular GameObjects.","triggerScenarios":"Calling UnpackPrefabInstance with a plain GameObject (not a prefab instance), a prefab asset in the Project window, or a GameObject inside a prefab editing context rather than a scene instance.","commonSituations":"Developer confused a prefab asset (in Project) with a prefab instance (in a scene), or tried to unpack a GameObject that was never a prefab instance. Also happens when operating on a freshly instantiated object that hasn't been connected to a prefab yet.","solutions":["Check PrefabUtility.IsPartOfNonAssetPrefabInstance(go) before calling UnpackPrefabInstance.","Verify the GameObject is in a scene (not in Project assets) using PrefabUtility.GetPrefabAssetType or IsPartOfPrefabAsset.","Use the correct API for assets: for prefab assets use different editor workflows, not UnpackPrefabInstance."],"exampleFix":"// before\nPrefabUtility.UnpackPrefabInstance(plainGo, PrefabUnpackMode.OutermostRoot, InteractionMode.UserAction);\n// after\nif (PrefabUtility.IsPartOfNonAssetPrefabInstance(go))\n    PrefabUtility.UnpackPrefabInstance(go, PrefabUnpackMode.OutermostRoot, InteractionMode.UserAction);","handlingStrategy":"validation","validationCode":"if (instanceRoot != null && PrefabUtility.IsPartOfNonAssetPrefabInstance(instanceRoot))\n    PrefabUtility.UnpackPrefabInstance(instanceRoot, mode, action);","typeGuard":"static bool IsUnpackablePrefabInstance(GameObject go) => go != null && PrefabUtility.IsPartOfNonAssetPrefabInstance(go);","tryCatchPattern":null,"preventionTips":["Distinguish prefab assets (in Project) from prefab instances (in scene)","Use IsPartOfNonAssetPrefabInstance to validate before unpack","Remember prefab assets cannot be unpacked, only instances in scenes"],"tags":["unity","prefab","argument-validation","editor"],"backgroundTag":null,"analyzedSha":"225b0fbdb57cc17d094e8056b71f8314aba56f73","analyzedAt":"2026-08-13T19:07:19.849Z","schemaVersion":2},"datasetVersion":"2026-08-13T19:17:28.613Z"}