{"record":{"id":"9d466e7aebcfdaac","repo":"nocobase/nocobase","slug":"plugin-options-name-unknown-load-error","errorCode":null,"errorMessage":"plugin [${options?.name || 'unknown'}] load error","messagePattern":"plugin \\[(.+?)\\] load error","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"packages/core/server/src/plugin-manager/plugin-manager.ts","lineNumber":355,"sourceCode":"    if (!options.name && typeof plugin === 'string') {\n      options.name = plugin;\n    }\n    if (typeof plugin === 'string' && options.name && !options.packageName) {\n      const packageName = await PluginManager.getPackageName(options.name);\n      if (packageName) {\n        options['packageName'] = packageName;\n      }\n    }\n    if (options.packageName) {\n      const packageJson = await PluginManager.getPackageJson(options.packageName);\n      options['packageJson'] = packageJson;\n      options['version'] = packageJson.version;\n    }\n\n    const P = await PluginManager.resolvePlugin(options.packageName || plugin, isUpgrade, !!options.packageName);\n\n    if (!P) {\n      throw new Error(`plugin [${options?.name || 'unknown'}] load error`);\n    }\n\n    const instance: Plugin = new P(createAppProxy(this.app), options);\n\n    this.pluginInstances.set(P, instance);\n    if (options.name) {\n      this.pluginAliases.set(options.name, instance);\n    }\n    if (options.packageName) {\n      this.pluginAliases.set(options.packageName, instance);\n    }\n    await instance.afterAdd();\n  }\n\n  async add(plugin?: string | typeof Plugin, options: any = {}, insert = false, isUpgrade = false) {\n    try {\n      await this.addOrThrow(plugin, options, insert, isUpgrade);\n    } catch (error) {","sourceCodeStart":337,"sourceCodeEnd":373,"githubUrl":"https://github.com/nocobase/nocobase/blob/fa42722fefe44265490dff2c27d79e2882bce4fa/packages/core/server/src/plugin-manager/plugin-manager.ts#L337-L373","documentation":"After resolving the plugin's package to a class via PluginManager.resolvePlugin(), addOrThrow() throws when the resolver returns a falsy value — i.e. the plugin module could not be resolved/loaded. The message includes the plugin name (or 'unknown' if no name was determined).","triggerScenarios":"Calling add/enable with a plugin name whose npm package is not installed in node_modules; a broken package.json/exports that the resolver cannot load; passing an invalid packageName option; dependency not installed after adding to package.json without yarn install.","commonSituations":"Deploying code that references a plugin not in package.json; a custom plugin built to the wrong dist path; npm/yarn install failed silently; plugin name typo mismatching the exported package; version upgrade removed the package.","solutions":["Run yarn/npm install so the plugin package exists in node_modules","Verify the plugin name/packageName spelling matches the actual package (@nocobase/plugin-xxx)","Check the package's main/module/exports fields point at a buildable/compiled entry","Rebuild the plugin (yarn build) if it is a local/custom plugin","Enable logs or call PluginManager.resolvePlugin(name) manually to see why resolution returns null"],"exampleFix":"// before\nawait app.pm.add('plugin-missing'); // load error\n// after\nyarn add @nocobase/plugin-missing\nawait app.pm.add('plugin-missing');","handlingStrategy":"validation","validationCode":"import fs from 'fs';\nfunction pluginPackageExists(name: string): boolean {\n  const candidates = [`node_modules/@nocobase/plugin-${name}`, `node_modules/${name}`];\n  return candidates.some((p) => fs.existsSync(p));\n}\nif (!pluginPackageExists('users')) throw new Error('run yarn install first');","typeGuard":"function isResolvablePluginClass(P: unknown): P is typeof Plugin {\n  return typeof P === 'function' && P.prototype instanceof Plugin;\n}","tryCatchPattern":"try {\n  await app.pm.add('users');\n} catch (e) {\n  if (e.message.includes('load error')) {\n    console.error('Plugin package missing or broken; run yarn install / yarn build');\n  } else throw e;\n}","preventionTips":["Commit correct package.json and run yarn install in CI before boot","Verify plugin main/exports point to built dist files","Rebuild custom plugins after source changes","Check startup logs for resolvePlugin failures"],"tags":["plugin-manager","module-resolution","npm","nocobase"],"backgroundTag":"plugin-module-not-found","analyzedSha":"fa42722fefe44265490dff2c27d79e2882bce4fa","analyzedAt":"2026-09-01T00:54:31.202Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T05:18:18.240Z"}