pixijs/pixijs · error · Error

The supplied Container must be a child of the caller

Error message

The supplied Container must be a child of the caller

What it means

`getChildIndex(child)` searches `this.children` for the given reference. If `indexOf` returns -1 the child does not belong to this container, so the lookup is impossible and the mixin throws. Other methods (`setChildIndex`, `addChildAt` re-parenting) call this to verify membership first.

Source

Thrown at src/scene/container/container-mixins/childrenHelperMixin.ts:347

    setChildIndex(child: ContainerChild, index: number): void
    {
        if (index < 0 || index >= this.children.length)
        {
            throw new Error(`The index ${index} supplied is out of bounds ${this.children.length}`);
        }

        this.getChildIndex(child); // check if child exists
        this.addChildAt(child, index);
    },

    getChildIndex(child: ContainerChild): number
    {
        const index = this.children.indexOf(child);

        if (index === -1)
        {
            throw new Error('The supplied Container must be a child of the caller');
        }

        return index;
    },

    addChildAt<U extends ContainerChild>(child: U, index: number): U
    {
        // #if _DEBUG
        if (!this.allowChildren)
        {
            deprecation(v8_0_0, 'addChildAt: Only Containers will be allowed to add children in v8.0.0');
        }
        // #endif

        const { children } = this;

        if (index < 0 || index > children.length)
        {

View on GitHub (pinned to 4b141e3ced)

Solutions

Check `child.parent === container` before calling `getChildIndex`.
Use the parent the child actually belongs to: `child.parent.getChildIndex(child)`.
If you only need to remove, call `child.removeFromParent()` instead of looking up the index manually.

Example fix

// before
const i = container.getChildIndex(child); // throws if child.parent !== container

// after
if (child.parent === container) {
  const i = container.getChildIndex(child);
} else if (child.parent) {
  const i = child.parent.getChildIndex(child);
}

Defensive patterns

Strategy: type-guard

Validate before calling

function safeGetChildIndex(container: { children: unknown[]; getChildIndex:(c:unknown)=>number }, child: unknown & { parent?: unknown }): number {
  return child && child.parent === container ? container.getChildIndex(child) : -1;
}

Type guard

function isChildOf(child: { parent?: unknown }, container: unknown): boolean {
  return !!child && child.parent === container;
}

Try / catch

try {
  i = container.getChildIndex(child);
} catch (err) {
  if (err.message.includes('must be a child of the caller')) {
    // child not in this container; use child.parent instead, or skip
  } else throw err;
}

Prevention

Always check `child.parent === container` before index operations.
Use `child.removeFromParent()` for removal to avoid manual index lookups.
Be wary of double-processing children after async events that may have moved them.

When it happens

Trigger: Calling `container.getChildIndex(child)` (or `setChildIndex`/`addChildAt`, which internally verify) with a child whose `.parent` is a different container, or which has already been removed. Also triggered by passing a detached/stale reference.

Common situations: Re-parenting logic that loses track of current parent; event handlers firing after a child was removed elsewhere; double-removal; using a child reference from one scene in another container's API.

Related errors

AI-assisted analysis of pixijs/pixijs@4b141e3ced (2026-08-12). Data as JSON: /api/errors/4739cd5469f92206. Report an issue: GitHub.