liabru/matter-js · info

Plugin.register: is already registered to different plugin o

Error message

Plugin.register: is already registered to different plugin object

What it means

A plugin with the same name and the SAME version is already registered, but it is a different object reference than the one being registered. The registry keeps the original; the second registration is ignored with a warning. This usually indicates duplicate module instantiation (the plugin file was evaluated twice, creating two distinct but identical objects).

Source

Thrown at src/core/Plugin.js:39

     * @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) {
        return Plugin._registry[Plugin.dependencyParse(dependency).name];
    };

View on GitHub (pinned to acb99b6f87)

Solutions

1. Register the plugin only once; guard with if (!Plugin._registry['name']) or remove duplicate script includes.
2. Dedupe the module in your bundler so all code shares one plugin instance.
3. If both objects are genuinely equivalent, this warning is safe to ignore — the first registration is used.
4. Bump the version if you intentionally ship a new plugin object.

Example fix

// before
Plugin.register(pluginObjA); // v1.0.0
Plugin.register(pluginObjB); // v1.0.0 but different object
// after
if (!Matter.Plugin._registry['my-plugin']) {
  Plugin.register(pluginObjA);
}

if (!Matter.Plugin._registry[plugin.name]) {
  Matter.Plugin.register(plugin);
}

When it happens

Trigger: Loading the plugin script twice without a version bump; bundler duplicating the module into two chunks so require/import yields two distinct objects; re-registering a re-created object of equal version.

Common situations: Mixing CDN script and bundled copy of the same plugin; multiple <script> tags; module federation/commonjs+esm dual loading.

Related errors

• Plugin.register: was upgraded to
• Plugin.register: can not be downgraded to
• Plugin.register: does not implement all required fields.
• Plugin.use: does not specify any dependencies to install.
• Plugin.use: is for but installed on .

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