Unity-Technologies/UnityCsReference · error · InvalidOperationException

Cannot replace the Prefab instance

Error message

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.

What it means

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.

Solutions

1. Ensure both the instance root and the new Prefab asset root use the same Transform type (RectTransform for UI, Transform for 3D).
2. Add a guard before the call: if (instanceRoot.transform.GetType() != assetRoot.transform.GetType()) skip or log a warning.
3. If the types genuinely differ, restructure one of the Prefabs so the root Transform type matches.

Example fix

// before
PrefabUtility.ReplacePrefabAssetOfPrefabInstance(sceneInstance, newPrefabAsset, mode);
// Fails if one root is RectTransform and the other is Transform

// after
if (sceneInstance.transform.GetType() == newPrefabAsset.transform.GetType())
    PrefabUtility.ReplacePrefabAssetOfPrefabInstance(sceneInstance, newPrefabAsset, mode);
else
    Debug.LogWarning($"Transform type mismatch: {sceneInstance.name} is {sceneInstance.transform.GetType().Name}, asset is {newPrefabAsset.transform.GetType().Name}");

if (prefabInstanceRoot.transform.GetType() != prefabAssetRoot.transform.GetType())
{
    Debug.LogError($"Transform type mismatch: {prefabInstanceRoot.transform.GetType().Name} vs {prefabAssetRoot.transform.GetType().Name}");
    return;
}
PrefabUtility.ReplacePrefabAssetOfPrefabInstance(prefabInstanceRoot, prefabAssetRoot, mode);

static bool TransformTypesMatch(GameObject instance, GameObject asset)
{
    return instance != null && asset != null
        && instance.transform.GetType() == asset.transform.GetType();
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Cannot convert the GameObject
• Input ' ' is not a plain GameObject, it is already a Prefab…
• Input ' ' is not a Prefab instance, for plain GameObjects…
• Input GameObject is using the HideFlags.DontSaveInEditor…
• Input instance is not an outermost Prefab instance root…

AI-assisted analysis of Unity-Technologies/UnityCsReference@225b0fbdb5 (2026-08-13). Data as JSON: /api/errors/264836b3e8ad1723. Report an issue: GitHub.

Appendix: source

Thrown at Editor/Mono/Prefabs/PrefabUtility.cs:2261

                throw new ArgumentNullException(nameof(prefabAssetRoot));

            if (checkValidAsset)
                ThrowIfInvalidAssetForReplacePrefabInstance(prefabAssetRoot, mode);

            if (!IsPartOfNonAssetPrefabInstance(prefabInstanceRoot))
                throw new InvalidOperationException(string.Format("Input '{0}' is not a Prefab instance, for plain GameObjects use ConvertToPrefabInstance() instead", prefabInstanceRoot.name));

            if (!IsOutermostPrefabInstanceRoot(prefabInstanceRoot))
                throw new ArgumentException("Input instance is not an outermost Prefab instance root. Input instance: " + prefabInstanceRoot.name, nameof(prefabInstanceRoot));
            if (EditorUtility.IsPersistent(prefabInstanceRoot))
                throw new ArgumentException("Input instance root is from a Prefab asset, this is not supported. Input instance: " + prefabInstanceRoot.name, nameof(prefabInstanceRoot));

            if (PrefabStageUtility.IsGameObjectThePrefabRootInAnyPrefabStage(prefabInstanceRoot))
                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);
            if (IsAnyPrefabInstanceRoot(prefabInstanceRoot) && EditorSceneManager.IsPreviewSceneObject(prefabInstanceRoot) && prefabInstanceRoot.transform.parent == null) // EditPrefabContentsScope handling
                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);
            if (prefabInstanceRoot.transform.GetType() != prefabAssetRoot.transform.GetType())
                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));

            if (prefabInstanceRoot.hideFlags.HasFlag(HideFlags.DontSaveInEditor) || prefabInstanceRoot.transform.hideFlags.HasFlag(HideFlags.DontSaveInEditor))
                throw new ArgumentException("Input instance root is using the HideFlags.DontSaveInEditor flag which is not supported when replacing: Input instance: " + prefabInstanceRoot.name, nameof(prefabInstanceRoot));

            if (mode == InteractionMode.UserAction)
            {
                // Recording undo does not handle missing scripts
                var gameObjectsWithInvalidScript = FindGameObjectsWithInvalidComponent(prefabInstanceRoot);
                if (gameObjectsWithInvalidScript.Count > 0)
                    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."));
            }
        }

        public static void ReplacePrefabAssetOfPrefabInstances(GameObject[] prefabInstanceRoots, GameObject prefabAssetRoot, InteractionMode mode)
        {
            ReplacePrefabAssetOfPrefabInstances(prefabInstanceRoots, prefabAssetRoot, new PrefabReplacingSettings(), mode);
        }

View on GitHub (pinned to 225b0fbdb5)