pixijs/pixijs · error · Error

RenderLayer.removeChild() is not available. Please use Rende

Error message

RenderLayer.removeChild() is not available. Please use RenderLayer.detach()

What it means

RenderLayer overrides `removeChild` to always throw. Because children are attached rather than owned via addChild, the symmetric removal is `detach()`. The override prevents the normal Container removal path from corrupting the layer's attachment state.

Source

Thrown at src/scene/layers/RenderLayer.ts:567

     * @throws {Error} Always throws an error as this method is not available.
     * @ignore
     */
    public override addChild<U extends Container[]>(..._children: U): never
    {
        throw new Error(
            'RenderLayer.addChild() is not available. Please use RenderLayer.attach()',
        );
    }
    /**
     * This method is not available in RenderLayer.
     * Calling this method will throw an error. Please use `RenderLayer.detach()` instead.
     * @param {...any} _children
     * @throws {Error} Always throws an error as this method is not available.
     * @ignore
     */
    public override removeChild<U extends Container[]>(..._children: U): never
    {
        throw new Error(
            'RenderLayer.removeChild() is not available. Please use RenderLayer.detach()',
        );
    }
    /**
     * This method is not available in RenderLayer.
     *
     * Calling this method will throw an error. Please use `RenderLayer.detach()` instead.
     * @param {number} [_beginIndex]
     * @param {number} [_endIndex]
     * @throws {Error} Always throws an error as this method is not available.
     * @ignore
     */
    public override removeChildren(_beginIndex?: number, _endIndex?: number): never
    {
        throw new Error(
            'RenderLayer.removeChildren() is not available. Please use RenderLayer.detach()',
        );
    }

View on GitHub (pinned to 4b141e3ced)

Solutions

Use `renderLayer.detach(child)` to detach a child from the layer.
Branch generic helpers on `instanceof RenderLayer` to call detach for layers.
If you need standard removal semantics, use a plain Container.

Example fix

// before
layer.removeChild(sprite); // throws

// after
layer.detach(sprite);

Defensive patterns

Strategy: type-guard

Validate before calling

function removeFromNode(node: RenderLayer | Container, child: Container) {
  if (node instanceof RenderLayer) (node as RenderLayer).detach(child as any);
  else (node as Container).removeChild(child);
}

Type guard

function isRenderLayer(node: unknown): node is RenderLayer {
  return !!node && node instanceof RenderLayer;
}

Try / catch

try {
  layer.removeChild(child);
} catch (err) {
  if (err.message.includes('RenderLayer.removeChild()')) {
    layer.detach(child);
  } else throw err;
}

Prevention

Branch cleanup helpers on RenderLayer.
Prefer `child.removeFromParent()` where available to avoid the Container/RenderLayer API split.
Wrap RenderLayer in a typed facade that exposes only detach.

When it happens

Trigger: Calling `renderLayer.removeChild(child)` on a RenderLayer; common when generic cleanup/teardown code walks a scene graph and calls removeChild on every node, or when porting Container cleanup code unchanged.

Common situations: Tear-down helpers, scene-disposal routines, drag-end handlers that call removeChild polymorphically; refactoring from Container to RenderLayer without revisiting removal calls.

Related errors

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