phaserjs/phaser · error · Error

Tried to add a Layer to a Container: this is not allowed

Error message

Tried to add a Layer to a Container: this is not allowed

What it means

Container.js:551 iterates an array of children and throws if any element is a `Layer`. Phaser forbids nesting a Layer inside a Container because Layers manage their own display list and depth handling via the renderer; mixing them corrupts rendering order and transforms.

Source

Thrown at src/gameobjects/container/Container.js:551

     * @method Phaser.GameObjects.Container#add
     * @since 3.4.0
     *
     * @generic {Phaser.GameObjects.GameObject} T
     * @genericUse {(T|T[])} - [child]
     *
     * @param {Phaser.GameObjects.GameObject|Phaser.GameObjects.GameObject[]} child - The Game Object, or array of Game Objects, to add to the Container.
     *
     * @return {this} This Container instance.
     */
    add: function (child)
    {
        if (Array.isArray(child))
        {
            child.forEach(function (value)
            {
                if (value && value instanceof Layer)
                {
                    throw new Error('Tried to add a Layer to a Container: this is not allowed');
                }
            });
        }
        else if (child && child instanceof Layer)
        {
            throw new Error('Tried to add a Layer to a Container: this is not allowed');
        }

        ArrayUtils.Add(this.list, child, this.maxSize, this.addHandler, this);

        return this;
    },

    /**
     * Adds the given Game Object, or array of Game Objects, to this Container at the specified position.
     *
     * Existing Game Objects in the Container are shifted up.
     *

View on GitHub (pinned to 41be1e462b)

Solutions

1. Add the Layer directly to the Scene's display list (`this.add.existing(layer)`) or to another Layer, never to a Container.
2. If you need grouping, use a Layer in place of the Container, or restructure so sprites live in the Container and the Layer is a sibling.
3. Filter the array before passing it to `add` to strip out Layer instances.

Example fix

// before
container.add([sprite, myLayer])
// after
this.add.existing(myLayer)
container.add([sprite])

const safe = children.filter(c => !(c instanceof Phaser.GameObjects.Layer))
container.add(safe)

const isLayer = (c) => c instanceof Phaser.GameObjects.Layer

When it happens

Trigger: Calling `container.add([sprite, layer, ...])` (or `addAt`, the array path) where one array element is a `Phaser.GameObjects.Layer`. The check is per-element during the array branch of `add`.

Common situations: Migrating a scene that used Containers for grouping and then introducing Layers for batched rendering; refactoring display hierarchies without noticing the Layer type; adding a ParticleEmitter's internal Layer by accident.

AI-assisted analysis of phaserjs/phaser@41be1e462b (2026-08-13). Data as JSON: /api/errors/46d570a8469d1519. Report an issue: GitHub.