{"record":{"id":"264836b3e8ad1723","repo":"Unity-Technologies/UnityCsReference","slug":"cannot-replace-the-prefab-instance-0-with-root","errorCode":null,"errorMessage":"Cannot replace the Prefab instance '{0}' with root transform of type {1} with a Prefab asset with root transform of type {2}. Transform types must match.","messagePattern":"Cannot replace the Prefab instance '(.+?)' with root transform of type (.+?) with a Prefab asset with root transform of type (.+?)\\. Transform types must match\\.","errorType":"exception","errorClass":"InvalidOperationException","httpStatus":null,"severity":"error","filePath":"Editor/Mono/Prefabs/PrefabUtility.cs","lineNumber":2261,"sourceCode":"                throw new ArgumentNullException(nameof(prefabAssetRoot));\n\n            if (checkValidAsset)\n                ThrowIfInvalidAssetForReplacePrefabInstance(prefabAssetRoot, mode);\n\n            if (!IsPartOfNonAssetPrefabInstance(prefabInstanceRoot))\n                throw new InvalidOperationException(string.Format(\"Input '{0}' is not a Prefab instance, for plain GameObjects use ConvertToPrefabInstance() instead\", prefabInstanceRoot.name));\n\n            if (!IsOutermostPrefabInstanceRoot(prefabInstanceRoot))\n                throw new ArgumentException(\"Input instance is not an outermost Prefab instance root. Input instance: \" + prefabInstanceRoot.name, nameof(prefabInstanceRoot));\n            if (EditorUtility.IsPersistent(prefabInstanceRoot))\n                throw new ArgumentException(\"Input instance root is from a Prefab asset, this is not supported. Input instance: \" + prefabInstanceRoot.name, nameof(prefabInstanceRoot));\n\n            if (PrefabStageUtility.IsGameObjectThePrefabRootInAnyPrefabStage(prefabInstanceRoot))\n                throw new InvalidOperationException(\"Replacing the root Prefab instance in a Variant is not supported since it will break all overrides for existing instances of this Variant, including their positions and rotations.\" + prefabInstanceRoot.name);\n            if (IsAnyPrefabInstanceRoot(prefabInstanceRoot) && EditorSceneManager.IsPreviewSceneObject(prefabInstanceRoot) && prefabInstanceRoot.transform.parent == null) // EditPrefabContentsScope handling\n                throw new InvalidOperationException(\"Replacing the Variant parent is not supported since it will break all overrides for existing instances of this Variant, including their positions and rotations.\" + prefabInstanceRoot.name);\n            if (prefabInstanceRoot.transform.GetType() != prefabAssetRoot.transform.GetType())\n                throw new InvalidOperationException(string.Format(\"Cannot replace the Prefab instance '{0}' with root transform of type {1} with a Prefab asset with root transform of type {2}. Transform types must match.\", prefabInstanceRoot.name, prefabInstanceRoot.transform.GetType().Name, prefabAssetRoot.transform.GetType().Name));\n\n            if (prefabInstanceRoot.hideFlags.HasFlag(HideFlags.DontSaveInEditor) || prefabInstanceRoot.transform.hideFlags.HasFlag(HideFlags.DontSaveInEditor))\n                throw new ArgumentException(\"Input instance root is using the HideFlags.DontSaveInEditor flag which is not supported when replacing: Input instance: \" + prefabInstanceRoot.name, nameof(prefabInstanceRoot));\n\n            if (mode == InteractionMode.UserAction)\n            {\n                // Recording undo does not handle missing scripts\n                var gameObjectsWithInvalidScript = FindGameObjectsWithInvalidComponent(prefabInstanceRoot);\n                if (gameObjectsWithInvalidScript.Count > 0)\n                    throw new InvalidOperationException(string.Format($\"Cannot replace the Prefab instance when it has a missing script. GameObject '{gameObjectsWithInvalidScript[0].name}' has a missing script. Use InteractionMode.AutomatedAction to force the replace.\"));\n            }\n        }\n\n        public static void ReplacePrefabAssetOfPrefabInstances(GameObject[] prefabInstanceRoots, GameObject prefabAssetRoot, InteractionMode mode)\n        {\n            ReplacePrefabAssetOfPrefabInstances(prefabInstanceRoots, prefabAssetRoot, new PrefabReplacingSettings(), mode);\n        }\n","sourceCodeStart":2243,"sourceCodeEnd":2279,"githubUrl":"https://github.com/Unity-Technologies/UnityCsReference/blob/225b0fbdb57cc17d094e8056b71f8314aba56f73/Editor/Mono/Prefabs/PrefabUtility.cs#L2243-L2279","documentation":"Thrown by ThrowIfInvalidArgumentsForReplacePrefabInstance when prefabInstanceRoot.transform.GetType() != prefabAssetRoot.transform.GetType(). The root Transform type of the target instance and the new Prefab asset must match (e.g. both UnityEngine.Transform, or both RectTransform). A mismatch — typically a UI Canvas RectTransform Prefab being swapped for a 3D Transform Prefab or vice versa — would break the hierarchy.","triggerScenarios":"Swapping a UI Prefab (root RectTransform) with a non-UI Prefab (root Transform), or the reverse. Replacing a Prefab whose root uses a custom Transform subclass with one that uses the base Transform.","commonSituations":"Generic 'replace Prefab' tool that doesn't differentiate UI (Canvas) Prefabs from 3D Prefabs. Art pipeline that regenerates Prefabs with different root structures across versions.","solutions":["Ensure both the instance root and the new Prefab asset root use the same Transform type (RectTransform for UI, Transform for 3D).","Add a guard before the call: if (instanceRoot.transform.GetType() != assetRoot.transform.GetType()) skip or log a warning.","If the types genuinely differ, restructure one of the Prefabs so the root Transform type matches."],"exampleFix":"// before\nPrefabUtility.ReplacePrefabAssetOfPrefabInstance(sceneInstance, newPrefabAsset, mode);\n// Fails if one root is RectTransform and the other is Transform\n\n// after\nif (sceneInstance.transform.GetType() == newPrefabAsset.transform.GetType())\n    PrefabUtility.ReplacePrefabAssetOfPrefabInstance(sceneInstance, newPrefabAsset, mode);\nelse\n    Debug.LogWarning($\"Transform type mismatch: {sceneInstance.name} is {sceneInstance.transform.GetType().Name}, asset is {newPrefabAsset.transform.GetType().Name}\");","handlingStrategy":"validation","validationCode":"if (prefabInstanceRoot.transform.GetType() != prefabAssetRoot.transform.GetType())\n{\n    Debug.LogError($\"Transform type mismatch: {prefabInstanceRoot.transform.GetType().Name} vs {prefabAssetRoot.transform.GetType().Name}\");\n    return;\n}\nPrefabUtility.ReplacePrefabAssetOfPrefabInstance(prefabInstanceRoot, prefabAssetRoot, mode);","typeGuard":"static bool TransformTypesMatch(GameObject instance, GameObject asset)\n{\n    return instance != null && asset != null\n        && instance.transform.GetType() == asset.transform.GetType();\n}","tryCatchPattern":null,"preventionTips":["Separate UI (RectTransform) Prefabs from 3D (Transform) Prefabs in your replacement mapping.","Add a transform-type guard in generic replace utilities."],"tags":["prefab","transform-type","rect-transform","argument-validation","unity-editor"],"backgroundTag":null,"analyzedSha":"225b0fbdb57cc17d094e8056b71f8314aba56f73","analyzedAt":"2026-08-13T19:07:19.849Z","schemaVersion":2},"datasetVersion":"2026-08-13T19:17:28.613Z"}