Unity-Technologies/UnityCsReference · error · ArgumentException

UnpackPrefabInstance must be called with a Prefab instance.

Error message

UnpackPrefabInstance must be called with a Prefab instance.

What it means

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.

Source

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

        internal static void Internal_CallPrefabInstanceReverted(GameObject instanceRoot)
        {
            Assert.IsNotNull(instanceRoot);

            prefabInstanceReverted?.Invoke(instanceRoot);
        }

        [AutoStaticsCleanupOnCodeReload]
        public static event Action<GameObject, PrefabUnpackMode> prefabInstanceUnpacking;
        [AutoStaticsCleanupOnCodeReload]
        public static event Action<GameObject, PrefabUnpackMode> prefabInstanceUnpacked;

        public static void UnpackPrefabInstance(GameObject instanceRoot, PrefabUnpackMode unpackMode, InteractionMode action)
        {
            if (instanceRoot == null)
                throw new ArgumentNullException(nameof(instanceRoot));

            if (!IsPartOfNonAssetPrefabInstance(instanceRoot))
                throw new ArgumentException("UnpackPrefabInstance must be called with a Prefab instance.");

            if (!IsOutermostPrefabInstanceRoot(instanceRoot))
                throw new ArgumentException("UnpackPrefabInstance must be called with a root Prefab instance GameObject.");

            if (action == InteractionMode.UserAction)
            {
                var undoActionName = "Unpack Prefab instance";
                Undo.RegisterFullObjectHierarchyUndo(instanceRoot, undoActionName);
                var newInstanceRoots = UnpackPrefabInstanceAndReturnNewOutermostRoots(instanceRoot, unpackMode);
                foreach (var newInstanceRoot in newInstanceRoots)
                {
                    var prefabInstance = PrefabUtility.GetPrefabInstanceHandle(newInstanceRoot);
                    if (prefabInstance)
                    {
                        Undo.RegisterCreatedObjectUndo(prefabInstance, undoActionName);
                    }
                }
            }

View on GitHub (pinned to 225b0fbdb5)

Solutions

1. Check PrefabUtility.IsPartOfNonAssetPrefabInstance(go) before calling UnpackPrefabInstance.
2. Verify the GameObject is in a scene (not in Project assets) using PrefabUtility.GetPrefabAssetType or IsPartOfPrefabAsset.
3. Use the correct API for assets: for prefab assets use different editor workflows, not UnpackPrefabInstance.

Example fix

// before
PrefabUtility.UnpackPrefabInstance(plainGo, PrefabUnpackMode.OutermostRoot, InteractionMode.UserAction);
// after
if (PrefabUtility.IsPartOfNonAssetPrefabInstance(go))
    PrefabUtility.UnpackPrefabInstance(go, PrefabUnpackMode.OutermostRoot, InteractionMode.UserAction);

if (instanceRoot != null && PrefabUtility.IsPartOfNonAssetPrefabInstance(instanceRoot))
    PrefabUtility.UnpackPrefabInstance(instanceRoot, mode, action);

static bool IsUnpackablePrefabInstance(GameObject go) => go != null && PrefabUtility.IsPartOfNonAssetPrefabInstance(go);

When it happens

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

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

Related errors

• plainGameObjects has no objects
• UnpackPrefabInstance must be called with a root Prefab insta
• Scene path cannot be null or empty.
• Path {scenePath} is not a scene path. Must end with .unity e
• No material targets provided

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