Unity-Technologies/UnityCsReference · error · ArgumentException

Target overlay has an invalid container

Error message

Target overlay has an invalid container

What it means

Thrown by OverlayPlacement.DockBefore when the target Overlay has a null container. Docking logic needs both overlays to belong to the same OverlayContainer to compute indices; an undocked target cannot be a dock reference.

Source

Thrown at Editor/Mono/Overlays/OverlayPlacement.cs:140

                index = sectionCount;
            }

            this.container.InsertOverlay(this, section, index, hint);

            floating = container is FloatingOverlayContainer;

            if (!existsInContainer)
                RebuildContent(false);

            dockingCompleted?.Invoke(container);

            return true;
        }

        internal bool DockBefore(Overlay target)
        {
            if (target.container == null)
                throw new ArgumentException("Target overlay has an invalid container", nameof(target));

            var targetContainer = target.container;
            targetContainer.GetOverlayIndex(target, out OverlayContainerSection section, out var targetIndex);
            if (container == targetContainer)
            {
                container.GetOverlayIndex(this, out OverlayContainerSection thisSection, out var thisIndex);
                if (thisIndex < targetIndex && thisSection == section)
                    targetIndex--;
            }

            return DockAt(targetContainer, section, targetIndex);
        }

        internal bool DockAfter(Overlay target)
        {
            if (target.container == null)
                throw new ArgumentException("Target overlay has an invalid container", nameof(target));

View on GitHub (pinned to 225b0fbdb5)

Solutions

1. Ensure the target overlay is docked into a container before calling DockBefore.
2. Check target.container != null before invoking.
3. Re-add the target to a container (e.g., overlayCanvas) first.

Example fix

// before
this.DockBefore(floatingTarget); // throws
// after
if (floatingTarget.container != null)
    this.DockBefore(floatingTarget);
else
    floatingTarget.DockInto(this.container);

if (target.container != null) this.DockBefore(target);

static bool IsDocked(Overlay o) => o.container != null;

When it happens

Trigger: Calling DockBefore(target) where target.container == null — target is floating/unparented.

Common situations: Target overlay was removed from its container but the reference is still held; ordering dock calls before the target has been placed into a container; UI state desync after a layout rebuild.

Related errors

• Cannot add dependency on invalid ArtifactKey.
• The object to add cannot be null.
• The object to remove cannot be null.
• Platform GUID {platformGuid} is not a valid Unity build plat
• rendererIDs and results NativeArrays don't match in length.

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