{"record":{"id":"7922c2ba0f630ff1","repo":"Unity-Technologies/UnityCsReference","slug":"input-instance-is-not-an-outermost-prefab-instance","errorCode":null,"errorMessage":"Input instance is not an outermost Prefab instance root. Input instance: ","messagePattern":"Input instance is not an outermost Prefab instance root\\. Input instance: ","errorType":"validation","errorClass":"ArgumentException","httpStatus":null,"severity":"error","filePath":"Editor/Mono/Prefabs/PrefabUtility.cs","lineNumber":2252,"sourceCode":"                throw new InvalidOperationException(string.Format($\"Cannot replace the Prefab instance with the Prefab Asset '{AssetDatabase.GetAssetPath(prefabAsset)}' because it has a missing script. GameObject '{gameObjectsWithInvalidScript[0].name}' in the Prefab Asset has a missing script.\"));\n        }\n\n        internal static void ThrowIfInvalidArgumentsForReplacePrefabInstance(GameObject prefabInstanceRoot, GameObject prefabAssetRoot, bool checkValidAsset, InteractionMode mode)\n        {\n            if (prefabInstanceRoot == null)\n                throw new ArgumentNullException(nameof(prefabInstanceRoot));\n\n            if (prefabAssetRoot == null)\n                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)","sourceCodeStart":2234,"sourceCodeEnd":2270,"githubUrl":"https://github.com/Unity-Technologies/UnityCsReference/blob/225b0fbdb57cc17d094e8056b71f8314aba56f73/Editor/Mono/Prefabs/PrefabUtility.cs#L2234-L2270","documentation":"Thrown by ThrowIfInvalidArgumentsForReplacePrefabInstance when IsOutermostPrefabInstanceRoot(prefabInstanceRoot) returns false. The API requires the top-level (outermost) Prefab instance root in the hierarchy — a nested child that is itself a Prefab instance is rejected because replacing only the inner instance would corrupt the parent instance structure.","triggerScenarios":"Passing a nested Prefab instance (a child object that is its own Prefab instance root but sits inside another Prefab instance) to ReplacePrefabAssetOfPrefabInstance. E.g. a weapon Prefab nested inside a character Prefab instance.","commonSituations":"Iterating over all Prefab instance roots found via GetRootGameObject on children and passing inner instances to the replace API. Selecting a deeply nested Prefab in the Hierarchy and running a bulk-replace script.","solutions":["Traverse up to the outermost parent Prefab instance using PrefabUtility.GetOutermostPrefabInstanceRoot(obj) and pass that instead.","Filter your candidate list with PrefabUtility.IsOutermostPrefabInstanceRoot(obj) before calling the API.","If you genuinely need to replace a nested instance, unpack the outer instance first, replace, then re-pack."],"exampleFix":"// before\nPrefabUtility.ReplacePrefabAssetOfPrefabInstance(nestedInstance, prefabAsset, mode);\n\n// after\nvar outer = PrefabUtility.GetOutermostPrefabInstanceRoot(nestedInstance);\nPrefabUtility.ReplacePrefabAssetOfPrefabInstance(outer, prefabAsset, mode);","handlingStrategy":"validation","validationCode":"// Resolve to the outermost root before calling\nvar outer = PrefabUtility.GetOutermostPrefabInstanceRoot(prefabInstanceRoot);\nif (outer != null && PrefabUtility.IsOutermostPrefabInstanceRoot(outer))\n    PrefabUtility.ReplacePrefabAssetOfPrefabInstance(outer, prefabAssetRoot, mode);","typeGuard":"static bool IsOutermostRoot(GameObject obj)\n{\n    return obj != null && PrefabUtility.IsOutermostPrefabInstanceRoot(obj);\n}","tryCatchPattern":null,"preventionTips":["Use PrefabUtility.GetOutermostPrefabInstanceRoot to normalize any instance reference before calling replace.","When iterating GetComponentsInChildren, filter out nested instance roots or resolve them to their outermost parent."],"tags":["prefab","argument-validation","nested-prefab","unity-editor"],"backgroundTag":null,"analyzedSha":"225b0fbdb57cc17d094e8056b71f8314aba56f73","analyzedAt":"2026-08-13T19:07:19.849Z","schemaVersion":2},"datasetVersion":"2026-08-13T19:17:28.613Z"}