{"record":{"id":"cac07d9dc99b4c99","repo":"mochajs/mocha","slug":"err-mocha-invalid-plugin-definition","errorCode":"ERR_MOCHA_INVALID_PLUGIN_DEFINITION","errorMessage":"pluginDef is non-object or falsy","messagePattern":"pluginDef is non-object or falsy","errorType":"error_code","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"lib/plugin-loader.js","lineNumber":188,"sourceCode":"\n    castArray(pluginDefs).forEach((pluginDef) => {\n      this.register(pluginDef);\n    });\n\n    debug(\n      \"registered %d plugin defs (%d ignored)\",\n      this.registered.size,\n      this.ignoredExportNames.size,\n    );\n  }\n\n  /**\n   * Register a plugin\n   * @param {PluginDefinition} pluginDef - Plugin definition\n   */\n  register(pluginDef) {\n    if (!pluginDef || typeof pluginDef !== \"object\") {\n      throw createInvalidPluginDefinitionError(\n        \"pluginDef is non-object or falsy\",\n        pluginDef,\n      );\n    }\n    if (!pluginDef.exportName) {\n      throw createInvalidPluginDefinitionError(\n        `exportName is expected to be a non-empty string`,\n        pluginDef,\n      );\n    }\n    let { exportName } = pluginDef;\n    if (this.ignoredExportNames.has(exportName)) {\n      debug(\n        'refusing to register ignored plugin with export name \"%s\"',\n        exportName,\n      );\n      return;\n    }","sourceCodeStart":170,"sourceCodeEnd":206,"githubUrl":"https://github.com/mochajs/mocha/blob/6bcbee4fd9a95351cedf0fdcb14c7d696486bc5a/lib/plugin-loader.js#L170-L206","documentation":"`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.","triggerScenarios":"Calling `loader.register(null)`, `register(undefined)`, `register('mochaGlobalSetup')` (a string instead of a definition object), or passing a variable that was never initialized.","commonSituations":"Custom tooling or extensions registering plugins programmatically; dynamic imports that resolved to undefined; refactors that changed register() to accept definitions instead of names.","solutions":["Pass a definition object: `loader.register({ exportName: 'mochaGlobalSetup', optionName: 'globalSetup', validate: fn })`.","Check the variable holding the definition is initialized before register().","If registering a built-in plugin, use the loader's own definitions instead of raw values."],"exampleFix":"// before\nloader.register('mochaGlobalSetup');\n// after\nloader.register({ exportName: 'mochaGlobalSetup', optionName: 'globalSetup', validate(v) { ... } });","handlingStrategy":"type-guard","validationCode":"if (!pluginDef || typeof pluginDef !== 'object') {\n  throw new Error('register() requires a plugin definition object');\n}","typeGuard":"function isPluginDefinition(v) {\n  return v != null && typeof v === 'object';\n}","tryCatchPattern":"try {\n  loader.register(pluginDef);\n} catch (err) {\n  if (err.code === 'ERR_MOCHA_INVALID_PLUGIN_DEFINITION') {\n    console.error('Pass an object like { exportName, optionName, validate }');\n  } else throw err;\n}","preventionTips":["Always pass object definitions, never names or strings","Check dynamic imports resolved before registering","Validate definition variables are initialized"],"tags":["plugins","api-misuse","argument-validation"],"backgroundTag":"invalid-plugin-definition","analyzedSha":"6bcbee4fd9a95351cedf0fdcb14c7d696486bc5a","analyzedAt":"2026-09-01T03:41:47.182Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}