phaserjs/phaser · error · Error

Cannot add Scene with duplicate key:

Error message

Cannot add Scene with duplicate key: 

What it means

Thrown by SceneManager.addScene when adding a Scene instance whose key already exists in this.keys. Scene keys must be unique per game so that the manager can address scenes unambiguously for start/stop/pause/resume and boot ordering.

Source

Thrown at src/scene/SceneManager.js:676

     *
     * @return {Phaser.Scene} The created Scene.
     */
    createSceneFromFunction: function (key, scene)
    {
        var newScene = new scene();

        if (newScene instanceof Scene)
        {
            var configKey = newScene.sys.settings.key;

            if (configKey !== '')
            {
                key = configKey;
            }

            if (this.keys.hasOwnProperty(key))
            {
                throw new Error('Cannot add Scene with duplicate key: ' + key);
            }

            return this.createSceneFromInstance(key, newScene);
        }
        else
        {
            newScene.sys = new Systems(newScene);

            newScene.sys.settings.key = key;

            newScene.sys.init(this.game);

            return newScene;
        }
    },

    /**
     * Creates and initializes a Scene instance.

View on GitHub (pinned to 41be1e462b)

Solutions

1. Use a unique key for each scene.
2. Before adding, check this.scene.keys.hasOwnProperty(key) or remove the existing scene first.
3. On restart/hot-reload, call this.scene.remove(key) before re-adding.
4. If the Scene's settings.key differs from the add() key, remember the manager prefers settings.key when non-empty.

Example fix

// before
this.scene.add('UI', uiScene); // 'UI' already registered

// after
if (this.scene.keys['UI']) this.scene.remove('UI');
this.scene.add('UI', uiScene);

function addSceneUnique(sceneManager, key, scene) {
  if (sceneManager.keys.hasOwnProperty(key)) {
    throw new Error(`Scene key '${key}' already in use`);
  }
  sceneManager.add(key, scene);
}

function isSceneKeyFree(sceneManager, key) { return !sceneManager.keys.hasOwnProperty(key); }

try { this.scene.add(key, scene); } catch (e) { if (/duplicate key/.test(e.message)) { this.scene.remove(key); this.scene.add(key, scene); } else throw e; }

When it happens

Trigger: Calling this.scene.add('key', sceneInstance) where 'key' (or the Scene's own settings.key) is already registered; adding a Scene class instance whose constructor config set a key that collides; re-adding a scene after a hot reload without removing the old one.

Common situations: Two scenes configured with the same key string; a plugin/scene that re-adds itself on every restart; refactoring and accidentally reusing a key; loading the same scene bundle twice.

Related errors

• Must set explicit renderType in custom environment
• Unknown value for renderer type:
• No DOM Container set in game config
• Invalid File type:
• Invalid File key:

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