{"record":{"id":"3285cbb22aa4cf62","repo":"Unity-Technologies/UnityCsReference","slug":"replacing-the-root-gameobject-in-a-prefab-with-a-p","errorCode":null,"errorMessage":"Replacing the root GameObject in a Prefab with a Prefab instance is not supported since it will break all overrides for existing instances of this Prefab, including their positions and rotations.","messagePattern":"Replacing the root GameObject in a Prefab with a Prefab instance is not supported since it will break all overrides for existing instances of this Prefab, including their positions and rotations\\.","errorType":"exception","errorClass":"InvalidOperationException","httpStatus":null,"severity":"error","filePath":"Editor/Mono/Prefabs/PrefabUtility.cs","lineNumber":2365,"sourceCode":"\n            if (prefabAssetRoot == null)\n                throw new ArgumentNullException(nameof(prefabAssetRoot));\n\n            if (IsPartOfNonAssetPrefabInstance(plainGameObject))\n                throw new InvalidOperationException(string.Format(\"Input '{0}' is not a plain GameObject, it is already a Prefab instance. Use ReplacePrefabAssetOfPrefabInstance() instead.\", plainGameObject.name));\n\n            if (EditorUtility.IsPersistent(plainGameObject))\n                throw new ArgumentException(\"Input is from a Prefab asset, this is not supported. Input GameObject: \" + plainGameObject.name, nameof(plainGameObject));\n\n            if (checkValidAsset)\n                ThrowIfInvalidAssetForReplacePrefabInstance(prefabAssetRoot, mode);\n\n            if (plainGameObject.transform.GetType() != prefabAssetRoot.transform.GetType())\n                throw new InvalidOperationException(string.Format(\"Cannot convert the GameObject '{0}' with root transform of type {1} with a Prefab asset with root transform of type {2}. Transform types must match.\", plainGameObject.name, plainGameObject.transform.GetType().Name, prefabAssetRoot.transform.GetType().Name));\n\n            // Prefab Mode and EditPrefabContents scope handling\n            if (PrefabStageUtility.IsGameObjectThePrefabRootInAnyPrefabStage(plainGameObject) || (EditorSceneManager.IsPreviewSceneObject(plainGameObject) && plainGameObject.transform.parent == null))\n                throw new InvalidOperationException(\"Replacing the root GameObject in a Prefab with a Prefab instance is not supported since it will break all overrides for existing instances of this Prefab, including their positions and rotations.\" + plainGameObject.name);\n\n            if (plainGameObject.hideFlags.HasFlag(HideFlags.DontSaveInEditor) || plainGameObject.transform.hideFlags.HasFlag(HideFlags.DontSaveInEditor))\n                throw new ArgumentException(\"Input GameObject is using the HideFlags.DontSaveInEditor flag which is not supported when converting to Prefab instance: GameObject: \" + plainGameObject.name, nameof(plainGameObject));\n\n            if (mode == InteractionMode.UserAction)\n            {\n                // Recording undo does not handle missing scripts\n                var gameObjectsWithInvalidScript = FindGameObjectsWithInvalidComponent(plainGameObject);\n                if (gameObjectsWithInvalidScript.Count > 0)\n                    throw new InvalidOperationException(string.Format($\"Cannot convert the GameObject when it has a missing script. GameObject '{gameObjectsWithInvalidScript[0].name}' has a missing script. This is not supported by the Undo system. Use InteractionMode.AutomatedAction instead.\"));\n            }\n        }\n\n        public static void ConvertToPrefabInstance(GameObject plainGameObject, GameObject prefabAssetRoot, ConvertToPrefabInstanceSettings settings, InteractionMode mode)\n        {\n            ThrowIfInvalidArgumentsForConvertToPrefabInstance(plainGameObject, prefabAssetRoot, true, mode);\n\n            ConvertToPrefabInstance_NoInputValidation(plainGameObject, prefabAssetRoot, settings, mode);","sourceCodeStart":2347,"sourceCodeEnd":2383,"githubUrl":"https://github.com/Unity-Technologies/UnityCsReference/blob/225b0fbdb57cc17d094e8056b71f8314aba56f73/Editor/Mono/Prefabs/PrefabUtility.cs#L2347-L2383","documentation":"Thrown by ThrowIfInvalidArgumentsForConvertToPrefabInstance when the plain GameObject is the root of a Prefab being edited in a Prefab Stage (PrefabStageUtility.IsGameObjectThePrefabRootInAnyPrefabStage) OR is an unparented object in a Preview Scene (EditPrefabContentsScope context). Converting the root of a Prefab/Variant to a Prefab instance would break all overrides on existing instances, so Unity blocks it.","triggerScenarios":"Opening a Prefab in Prefab Mode and running a script that calls ConvertToPrefabInstance on the root. Using EditPrefabContentsScope to load a Prefab and converting its root to a different Prefab instance.","commonSituations":"Editor scripts that run while a Prefab Stage is open. Batch tools that load Prefab contents and try to convert the root rather than children.","solutions":["Convert a child object inside the Prefab, not the root, if you need to nest a Prefab instance.","Close the Prefab Stage (StageUtility.GoToMainStage) and operate on a scene instance instead.","Use PrefabUtility.SaveAsPrefabAsset to restructure the Prefab asset rather than converting its root."],"exampleFix":"// before\nusing (var scope = new PrefabUtility.EditPrefabContentsScope(prefabPath))\n{\n    PrefabUtility.ConvertToPrefabInstance(scope.prefabContentsRoot, nestedPrefabAsset, settings, mode);\n}\n\n// after — convert a child, not the root\nusing (var scope = new PrefabUtility.EditPrefabContentsScope(prefabPath))\n{\n    var child = scope.prefabContentsRoot.transform.Find(\"Slot\").gameObject;\n    PrefabUtility.ConvertToPrefabInstance(child, nestedPrefabAsset, settings, mode);\n}","handlingStrategy":"validation","validationCode":"if (PrefabStageUtility.IsGameObjectThePrefabRootInAnyPrefabStage(plainGameObject)\n    || (EditorSceneManager.IsPreviewSceneObject(plainGameObject) && plainGameObject.transform.parent == null))\n{\n    Debug.LogError(\"Cannot convert the root of a Prefab/Variant to a Prefab instance; convert a child instead.\");\n    return;\n}\nPrefabUtility.ConvertToPrefabInstance(plainGameObject, prefabAssetRoot, settings, mode);","typeGuard":"static bool IsSafeToConvert(GameObject obj)\n{\n    return obj != null\n        && !PrefabStageUtility.IsGameObjectThePrefabRootInAnyPrefabStage(obj)\n        && !(EditorSceneManager.IsPreviewSceneObject(obj) && obj.transform.parent == null);\n}","tryCatchPattern":null,"preventionTips":["Inside EditPrefabContentsScope, only convert child objects, never the root.","Check Prefab Stage state before running conversion scripts."],"tags":["prefab","prefab-stage","preview-scene","edit-prefab-contents","unity-editor"],"backgroundTag":null,"analyzedSha":"225b0fbdb57cc17d094e8056b71f8314aba56f73","analyzedAt":"2026-08-13T19:07:19.849Z","schemaVersion":2},"datasetVersion":"2026-08-13T19:17:28.613Z"}