liabru/matter-js · info

Plugin.register: was upgraded to

Error message

Plugin.register: was upgraded to

What it means

Plugin.register found a plugin already registered under the same name with a LOWER version; the new (higher-version) plugin replaces it in the registry, but a warning informs you an upgrade occurred. This is informational: the newer plugin wins. It matters because two code paths registering different versions of the same-named plugin cause unexpected replacement.

Source

Thrown at src/core/Plugin.js:34

    /**
     * Registers a plugin object so it can be resolved later by name.
     * @method register
     * @param plugin {} The plugin to register.
     * @return {object} The plugin.
     */
    Plugin.register = function(plugin) {
        if (!Plugin.isPlugin(plugin)) {
            Common.warn('Plugin.register:', Plugin.toString(plugin), 'does not implement all required fields.');
        }

        if (plugin.name in Plugin._registry) {
            var registered = Plugin._registry[plugin.name],
                pluginVersion = Plugin.versionParse(plugin.version).number,
                registeredVersion = Plugin.versionParse(registered.version).number;

            if (pluginVersion > registeredVersion) {
                Common.warn('Plugin.register:', Plugin.toString(registered), 'was upgraded to', Plugin.toString(plugin));
                Plugin._registry[plugin.name] = plugin;
            } else if (pluginVersion < registeredVersion) {
                Common.warn('Plugin.register:', Plugin.toString(registered), 'can not be downgraded to', Plugin.toString(plugin));
            } else if (plugin !== registered) {
                Common.warn('Plugin.register:', Plugin.toString(plugin), 'is already registered to different plugin object');
            }
        } else {
            Plugin._registry[plugin.name] = plugin;
        }

        return plugin;
    };

    /**
     * Resolves a dependency to a plugin object from the registry if it exists. 
     * The `dependency` may contain a version, but only the name matters when resolving.
     * @method resolve
     * @param dependency {string} The dependency.

View on GitHub (pinned to acb99b6f87)

Solutions

1. Remove the older plugin registration/duplicate script tag so only one version loads.
2. If intentional, silence awareness: the newer plugin IS active; update code that referenced the old version's API.
3. Consolidate plugin versions in your build (dedupe in package.json/bundler).

Example fix

// before
Plugin.register(pA); // v1.0.0
Plugin.register(pB); // v1.1.0, same name -> upgrade warning
// after
Plugin.register(pB); // register only the latest version

const existing = Matter.Plugin._registry[plugin.name];
if (!existing || Matter.Plugin.versionParse(plugin.version).number > Matter.Plugin.versionParse(existing.version).number) {
  Matter.Plugin.register(plugin);
}

// warning only: no throw; log if unexpected
const origWarn = Matter.Common.warn;
Matter.Common.warn = (...args) => {
  if (args.join(' ').includes('was upgraded to')) console.debug('plugin upgraded:', ...args);
  origWarn(...args);
};

When it happens

Trigger: Calling Plugin.register twice for the same plugin.name where the second object's semver version is greater — e.g. loading two bundles containing different versions of the same plugin.

Common situations: Duplicate script includes of a plugin at different versions; upgrading a plugin while an old copy is still loaded; bundling the plugin multiple times.

Related errors

• Plugin.register: can not be downgraded to
• Plugin.register: is already registered to different plugin o
• Plugin.use: is for but installed on .
• Plugin.register: does not implement all required fields.
• Plugin.use: does not specify any dependencies to install.

AI-assisted analysis of liabru/matter-js@acb99b6f87 (2026-09-02). Data as JSON: /api/errors/a96c7d2fdb4447e2. Report an issue: GitHub.