liabru/matter-js · warning

Plugin.register: can not be downgraded to

Error message

Plugin.register: can not be downgraded to

What it means

Plugin.register was given a plugin whose name is already registered with a HIGHER version; the downgrade is refused (the higher-version registered plugin is kept) and a warning is emitted. This protects you from accidentally overwriting a newer plugin with an older copy.

Source

Thrown at src/core/Plugin.js:37

     * @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.
     * @return {object} The plugin if resolved, otherwise `undefined`.
     */
    Plugin.resolve = function(dependency) {

View on GitHub (pinned to acb99b6f87)

Solutions

1. Ensure only one (the newest) version of the plugin is loaded/registered.
2. Check registered versions via Plugin._registry or Plugin.toString output in the warning.
3. Update the old copy to the newer version, or reorder includes so the newest loads last if last-write-wins is desired.

Example fix

// before
Plugin.register(pNew); // v2.0.0
Plugin.register(pOld); // v1.0.0 -> downgrade refused
// after
Plugin.register(pNew); // only register the newest 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);
} else {
  console.warn('Skipping downgrade of', plugin.name, 'to', plugin.version);
}

When it happens

Trigger: Registering the same plugin.name with a smaller semver than what is already in Plugin._registry — typically loading an old plugin file after a new one.

Common situations: Stale cached script loaded after the updated one; two dependencies pinning different plugin versions; rollback attempts at runtime.

Related errors

• Plugin.register: was upgraded 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/5fe799505e6cb215. Report an issue: GitHub.