liabru/matter-js · warning

Plugin.use: does not specify an install function.

Error message

Plugin.use: does not specify an install function.

What it means

Matter.Plugin.use registers a plugin by calling its install function. When a plugin object passed to Plugin.use (directly or via plugin list in Matter.use) has no install function, the library logs this warning and skips installation. The plugin still appears in warnings as '🔶' but is not initialized.

Source

Thrown at src/core/Plugin.js:160

            if (!plugin) {
                status.push('❌ ' + sortedDependencies[i]);
                continue;
            }

            if (Plugin.isUsed(module, plugin.name)) {
                continue;
            }

            if (!Plugin.isFor(plugin, module)) {
                Common.warn('Plugin.use:', Plugin.toString(plugin), 'is for', plugin.for, 'but installed on', Plugin.toString(module) + '.');
                plugin._warned = true;
            }

            if (plugin.install) {
                plugin.install(module);
            } else {
                Common.warn('Plugin.use:', Plugin.toString(plugin), 'does not specify an install function.');
                plugin._warned = true;
            }

            if (plugin._warned) {
                status.push('🔶 ' + Plugin.toString(plugin));
                delete plugin._warned;
            } else {
                status.push('✅ ' + Plugin.toString(plugin));
            }

            module.used.push(plugin.name);
        }

        if (status.length > 0) {
            Common.info(status.join('  '));
        }
    };

View on GitHub (pinned to acb99b6f87)

Solutions

1. Add an install function to the plugin object: plugin.install = function(module) { ... } before calling Matter.use.
2. Register the plugin function/class via Plugin.register(MyPlugin) and use the returned plugin object (register attaches install).
3. Verify you are passing the plugin object, not the plugin namespace or factory, into Matter.use.

Example fix

// before
Matter.use({ name: 'my-plugin', version: '0.1.0' });
// after
Matter.use({
  name: 'my-plugin',
  version: '0.1.0',
  install: function(matter) { /* extend matter here */ }
});

if (typeof plugin !== 'object' || typeof plugin.install !== 'function') {
  throw new TypeError('Plugin must define an install function before Matter.use(plugin)');
}

function isInstallablePlugin(p) {
  return p !== null && typeof p === 'object' && typeof p.install === 'function';
}

When it happens

Trigger: Calling Matter.use(plugin) or Matter.Plugin.use(module, plugin) where plugin is an object without an install function property, or plugin is not registered via Plugin.register (which would return a valid plugin object).

Common situations: Hand-written plugin objects that only define a name/version but no install(module) method; passing a plugin constructor (class/function) instead of its registered instance; typos like 'instal' or install defined on the prototype of an unregistered function; loading a plugin module that exports metadata but no install.

Related errors

• Plugin.register: does not implement all required fields.
• Plugin.register: was upgraded to
• Plugin.register: can not be downgraded to
• Plugin.register: is already registered to different plugin o
• 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/60f3c1a9268f694b. Report an issue: GitHub.