Unity-Technologies/UnityCsReference · error · ArgumentException

Cyclic nesting detected

Error message

Cyclic nesting detected

What it means

Thrown when VerifyNestingFromScript returns false, indicating that connecting the GameObjects into the target prefab would create a cyclic prefab nesting (a prefab eventually containing itself). Unity performs a native graph check before the connect call to prevent infinite recursion in the prefab hierarchy.

Source

Thrown at Editor/Mono/Prefabs/PrefabUtility.bindings.cs:326

                {
                    if (parentPrefabInstance != targetPrefabInstance)
                    {
                        throw new ArgumentException("GameObjects must be parented under the same Prefab instance.");
                    }
                }

                if (PrefabUtility.IsPartOfNonAssetPrefabInstance(go))
                {
                    var correspondingGO = PrefabUtility.GetCorrespondingObjectFromSource(go);
                    var correspondingGOPrefabObject = PrefabUtility.GetPrefabAssetHandle(correspondingGO);
                    if (targetPrefabObject == correspondingGOPrefabObject)
                        throw new ArgumentException("GameObject is already part of target prefab");
                }
            }

            string prefabGUID = AssetDatabase.AssetPathToGUID(AssetDatabase.GetAssetPath(targetPrefab));
            if (!VerifyNestingFromScript(gameObjects, prefabGUID, null))
                throw new ArgumentException("Cyclic nesting detected");

            AddGameObjectsToPrefabAndConnect_Internal(gameObjects, targetPrefab);
        }

        [NativeMethod("AddGameObjectsToPrefabAndConnect", IsFreeFunction = true)]
        extern private static void AddGameObjectsToPrefabAndConnect_Internal([NotNull] GameObject[] gameObjects, [NotNull] Object prefab);

        [NativeMethod("VerifyNestingFromScript", IsFreeFunction = true)]
        extern private static bool VerifyNestingFromScript([NotNull] GameObject[] gameObjects, [NotNull] string targetPrefabGUID, Object prefabInstance);

        [StaticAccessor("PrefabUtilityBindings", StaticAccessorType.DoubleColon)]
        [NativeMethod(ThrowsException = true)]
        extern internal static Component[] GetRemovedComponents([NotNull] Object prefabInstance);

        [StaticAccessor("PrefabUtilityBindings", StaticAccessorType.DoubleColon)]
        [NativeMethod(ThrowsException = true)]
        extern static void SetRemovedComponents([NotNull] Object prefabInstance, [NotNull] Component[] removedComponents);

View on GitHub (pinned to 225b0fbdb5)

Solutions

1. Break the cycle: ensure the target prefab is not already nested under any prefab referenced by the objects being connected.
2. Audit the nesting graph of target and inputs before calling.
3. Use a separate, non-cyclic prefab as the target, or flatten the conflicting nesting first.

Example fix

// before
// A nests B, B nests A-equivalent -> cyclic
PrefabUtility.AddGameObjectsToPrefabAndConnect(gos, targetA);

// after
// VerifyNestingFromScript mirrors the native check; if it returns false, abort.
// Restructure so target is not an ancestor of the inputs' source prefabs.
if (!VerifyNoCycle(gos, target)) { Debug.LogError("Would create a cycle."); return; }
PrefabUtility.AddGameObjectsToPrefabAndConnect(gos, target);

// Mirror the native guard: build the nesting graph and reject cycles before calling.
// Unity does not expose VerifyNestingFromScript publicly; track ancestor GUIDs manually.
if (WouldCreateCycle(gameObjects, targetPrefab))
{ Debug.LogError("Connecting would create a cyclic prefab nesting."); return; }

When it happens

Trigger: Nesting prefab A inside prefab B when B (or its variant) is already nested under A, forming a cycle. Variants and nested prefabs that, through overrides applied to the target, would reference back to an ancestor.

Common situations: Building recursive/recursive-looking prefab structures. Connecting a child whose corresponding prefab is an ancestor of the target in the nesting graph. Restructuring prefabs without checking the existing nesting chain.

Related errors

• gameObjects
• gameObjects array is empty
• targetPrefab
• Target Prefab has to be a Prefab Asset
• GameObject in input 'gameObjects' array is null

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