phaserjs/phaser · error · Error

No DOM Container set in game config

Error message

No DOM Container set in game config

What it means

DOMElement.js:135 reads `scene.sys.game.domContainer`; if it is null, Phaser did not create the DOM container and throws. The container is only created when `dom.createContainer: true` is set in the game config (Config.js:209, default false). DOMElement objects must live inside that div to be positioned over/under the canvas.

Source

Thrown at src/gameobjects/domelement/DOMElement.js:135

    initialize:

    function DOMElement (scene, x, y, element, style, innerText)
    {
        GameObject.call(this, scene, 'DOMElement');

        /**
         * A reference to the parent DOM Container that the Game instance created when it started.
         *
         * @name Phaser.GameObjects.DOMElement#parent
         * @type {Element}
         * @since 3.17.0
         */
        this.parent = scene.sys.game.domContainer;

        if (!this.parent)
        {
            throw new Error('No DOM Container set in game config');
        }

        /**
         * A reference to the HTML Cache.
         *
         * @name Phaser.GameObjects.DOMElement#cache
         * @type {Phaser.Cache.BaseCache}
         * @since 3.17.0
         */
        this.cache = scene.sys.cache.html;

        /**
         * The actual DOM Element that this Game Object is bound to. For example, if you've created a `<div>`
         * then this property is a direct reference to that element within the dom.
         *
         * @name Phaser.GameObjects.DOMElement#node
         * @type {Element}
         * @since 3.17.0

View on GitHub (pinned to 41be1e462b)

Solutions

1. Add `dom: { createContainer: true }` to the Phaser.Game config object before any DOMElement is created.
2. Optionally set `dom: { createContainer: true, behindCanvas: true }` to control z-ordering relative to the canvas.
3. Restart the game instance after changing config (config is read once at boot).

Example fix

// before
new Phaser.Game({ width: 800, height: 600, scene: MyScene })
// after
new Phaser.Game({ width: 800, height: 600, dom: { createContainer: true }, scene: MyScene })

const needsDom = sceneConfigUsesDomElements
if (needsDom && !gameConfig.dom?.createContainer) {
  throw new Error('Enable dom.createContainer in game config before using DOMElement')
}

When it happens

Trigger: Instantiating `this.add.dom(x, y, element)` (or `new DOMElement(scene, x, y, element)`) in a scene while the game config omits `dom: { createContainer: true }`. The DOMElementFactory and DOMElement docs both require this config.

Common situations: Following a DOM-element tutorial without copying the config block; enabling DOM elements mid-project and forgetting the global config; running where the parent element selector resolves but the container was never made.

Related errors

• Must set explicit renderType in custom environment
• Unknown value for renderer type:
• Cannot create WebGL context, aborting.
• Cannot create Canvas context, aborting.
• Invalid File type:

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