Unity-Technologies/UnityCsReference · error · ArgumentException

Prefab Mode: GameObject must be part of a Prefab instance, o

Error message

Prefab Mode: GameObject must be part of a Prefab instance, or null.

What it means

Thrown by PrefabStage.SetOpenedFromInstanceObject when the provided GameObject is non-null but PrefabUtility.IsPartOfPrefabInstance returns false. The method records which prefab instance object the user initiated prefab editing from, so the argument must be an actual instance of a prefab in a scene (or null). A loose asset reference or a plain non-prefab scene object triggers this guard.

Source

Thrown at Editor/Mono/SceneManagement/StageManager/PrefabStage/PrefabStage.cs:200

            Transform transform = prefabInstanceObject.transform;
            while (transform != null)
            {
                var assetObject = PrefabUtility.GetCorrespondingObjectFromSourceAtPath(transform, prefabAssetPath);
                if (assetObject != null && assetObject.parent == null)
                    return transform.gameObject;

                transform = transform.parent;
            }

            return null;
        }

        void SetOpenedFromInstanceObject(GameObject go)
        {
            if (go != null)
            {
                if (!PrefabUtility.IsPartOfPrefabInstance(go))
                    throw new ArgumentException("Prefab Mode: GameObject must be part of a Prefab instance, or null.", nameof(go));

                m_OpenedFromInstanceObject = go;
                m_OpenedFromInstanceRoot = FindPrefabInstanceRootThatMatchesPrefabAssetPath(go, m_PrefabAssetPath);
                if (m_OpenedFromInstanceRoot == null)
                    throw new ArgumentException($"Prefab Mode: The 'openedFromInstance' GameObject '{go.name}' is unrelated to the Prefab Asset '{m_PrefabAssetPath}'.");

                m_FileIdForOpenedFromInstanceObject = Unsupported.GetOrGenerateFileIDHint(go);
            }
            else
            {
                m_OpenedFromInstanceObject = null;
                m_OpenedFromInstanceRoot = null;
                m_FileIdForOpenedFromInstanceObject = 0;
            }
        }

        void ReconstructInContextStateIfNeeded()
        {

View on GitHub (pinned to 225b0fbdb5)

Solutions

1. Verify PrefabUtility.IsPartOfPrefabInstance(go) is true before calling the API; pass null if you have no instance to associate.
2. If you only have a project asset, pass null for openedFromInstance.
3. Ensure the GameObject reference comes from a loaded scene hierarchy, not from AssetDatabase/Project window.

Example fix

// before
stage.SetOpenedFromInstanceObject(myGameObject);

// after
if (myGameObject != null && PrefabUtility.IsPartOfPrefabInstance(myGameObject))
    stage.SetOpenedFromInstanceObject(myGameObject);
else
    stage.SetOpenedFromInstanceObject(null);

bool CanSetOpenedFromInstance(GameObject go)
{
    return go == null || PrefabUtility.IsPartOfPrefabInstance(go);
}

static bool IsValidPrefabInstanceObject(GameObject go)
    => go == null || PrefabUtility.IsPartOfPrefabInstance(go);

When it happens

Trigger: Calling PrefabStage API with a GameObject that exists in a scene but is not an instance of any prefab asset. Passing the prefab asset itself (from the Project window) rather than an instance in a scene. Passing a GameObject that was a prefab instance but has been disconnected/ unpacked.

Common situations: Programmatically opening a prefab stage via an editor script and accidentally passing a project-asset reference. Script that walks the hierarchy and picks an object that turns out not to be a prefab instance. After unpacking a prefab instance, stale references are passed to the API.

Related errors

• Prefab Mode: The 'openedFromInstance' GameObject '{go.name}'
• Cannot save as new prefab using the same path
• GameObject must be part of a Prefab instance, or null.
• Incorrect file extension: {prefabAssetPath}. Must be '.prefa
• Prefab not found at path {prefabAssetPath}

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