{"record":{"id":"46d570a8469d1519","repo":"phaserjs/phaser","slug":"tried-to-add-a-layer-to-a-container-this-is-not-a","errorCode":null,"errorMessage":"Tried to add a Layer to a Container: this is not allowed","messagePattern":"Tried to add a Layer to a Container: this is not allowed","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"src/gameobjects/container/Container.js","lineNumber":551,"sourceCode":"     * @method Phaser.GameObjects.Container#add\n     * @since 3.4.0\n     *\n     * @generic {Phaser.GameObjects.GameObject} T\n     * @genericUse {(T|T[])} - [child]\n     *\n     * @param {Phaser.GameObjects.GameObject|Phaser.GameObjects.GameObject[]} child - The Game Object, or array of Game Objects, to add to the Container.\n     *\n     * @return {this} This Container instance.\n     */\n    add: function (child)\n    {\n        if (Array.isArray(child))\n        {\n            child.forEach(function (value)\n            {\n                if (value && value instanceof Layer)\n                {\n                    throw new Error('Tried to add a Layer to a Container: this is not allowed');\n                }\n            });\n        }\n        else if (child && child instanceof Layer)\n        {\n            throw new Error('Tried to add a Layer to a Container: this is not allowed');\n        }\n\n        ArrayUtils.Add(this.list, child, this.maxSize, this.addHandler, this);\n\n        return this;\n    },\n\n    /**\n     * Adds the given Game Object, or array of Game Objects, to this Container at the specified position.\n     *\n     * Existing Game Objects in the Container are shifted up.\n     *","sourceCodeStart":533,"sourceCodeEnd":569,"githubUrl":"https://github.com/phaserjs/phaser/blob/41be1e462bc600064e498cba370bfa8c5c055a22/src/gameobjects/container/Container.js#L533-L569","documentation":"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.","triggerScenarios":"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`.","commonSituations":"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.","solutions":["Add the Layer directly to the Scene's display list (`this.add.existing(layer)`) or to another Layer, never to a Container.","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.","Filter the array before passing it to `add` to strip out Layer instances."],"exampleFix":"// before\ncontainer.add([sprite, myLayer])\n// after\nthis.add.existing(myLayer)\ncontainer.add([sprite])","handlingStrategy":"type-guard","validationCode":"const safe = children.filter(c => !(c instanceof Phaser.GameObjects.Layer))\ncontainer.add(safe)","typeGuard":"const isLayer = (c) => c instanceof Phaser.GameObjects.Layer","tryCatchPattern":null,"preventionTips":["Never pass a Layer to Container.add/addAt; add Layers to the Scene display list or another Layer.","When refactoring display hierarchies, grep for `.add(` calls involving Layers.","Write a small wrapper that filters Layers out before delegating to Container.add."],"tags":["gameobjects","container","layer","display-list"],"backgroundTag":null,"analyzedSha":"41be1e462bc600064e498cba370bfa8c5c055a22","analyzedAt":"2026-08-13T04:23:39.729Z","schemaVersion":2},"datasetVersion":"2026-08-13T09:17:06.757Z"}