mochajs/mocha · error · Error

ERR_MOCHA_INVALID_PLUGIN_DEFINITION

ERR_MOCHA_INVALID_PLUGIN_DEFINITION

Error message

pluginDef is non-object or falsy

What it means

`PluginLoader.register` (lib/plugin-loader.js:188) throws ERR_MOCHA_INVALID_PLUGIN_DEFINITION when the `pluginDef` argument is falsy or not an object. Registering a plugin requires a PluginDefinition object with at least an `exportName`; this is the first structural check, run before the exportName checks.

Source

Thrown at lib/plugin-loader.js:188

    castArray(pluginDefs).forEach((pluginDef) => {
      this.register(pluginDef);
    });

    debug(
      "registered %d plugin defs (%d ignored)",
      this.registered.size,
      this.ignoredExportNames.size,
    );
  }

  /**
   * Register a plugin
   * @param {PluginDefinition} pluginDef - Plugin definition
   */
  register(pluginDef) {
    if (!pluginDef || typeof pluginDef !== "object") {
      throw createInvalidPluginDefinitionError(
        "pluginDef is non-object or falsy",
        pluginDef,
      );
    }
    if (!pluginDef.exportName) {
      throw createInvalidPluginDefinitionError(
        `exportName is expected to be a non-empty string`,
        pluginDef,
      );
    }
    let { exportName } = pluginDef;
    if (this.ignoredExportNames.has(exportName)) {
      debug(
        'refusing to register ignored plugin with export name "%s"',
        exportName,
      );
      return;
    }

View on GitHub (pinned to 6bcbee4fd9)

Solutions

1. Pass a definition object: `loader.register({ exportName: 'mochaGlobalSetup', optionName: 'globalSetup', validate: fn })`.
2. Check the variable holding the definition is initialized before register().
3. If registering a built-in plugin, use the loader's own definitions instead of raw values.

Example fix

// before
loader.register('mochaGlobalSetup');
// after
loader.register({ exportName: 'mochaGlobalSetup', optionName: 'globalSetup', validate(v) { ... } });

if (!pluginDef || typeof pluginDef !== 'object') {
  throw new Error('register() requires a plugin definition object');
}

function isPluginDefinition(v) {
  return v != null && typeof v === 'object';
}

try {
  loader.register(pluginDef);
} catch (err) {
  if (err.code === 'ERR_MOCHA_INVALID_PLUGIN_DEFINITION') {
    console.error('Pass an object like { exportName, optionName, validate }');
  } else throw err;
}

When it happens

Trigger: Calling `loader.register(null)`, `register(undefined)`, `register('mochaGlobalSetup')` (a string instead of a definition object), or passing a variable that was never initialized.

Common situations: Custom tooling or extensions registering plugins programmatically; dynamic imports that resolved to undefined; refactors that changed register() to accept definitions instead of names.

Related errors

• Not enough non-option arguments: got 0, need at least 1
• Not enough arguments following: ${name}
• Missing runner argument
• Missing runner argument
• ERR_MOCHA_INVALID_ARG_TYPE

AI-assisted analysis of mochajs/mocha@6bcbee4fd9 (2026-09-01). Data as JSON: /api/errors/cac07d9dc99b4c99. Report an issue: GitHub.