{"record":{"id":"b002e18b3e076e2c","repo":"immich-app/immich","slug":"unable-to-instantiate-plugin-key","errorCode":null,"errorMessage":"Unable to instantiate plugin: ${key}","messagePattern":"Unable to instantiate plugin: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"server/src/repositories/plugin.repository.ts","lineNumber":240,"sourceCode":"                info: (message) => logger.log(message),\n                debug: (message) => logger.debug(message),\n                warn: (message) => logger.warn(message),\n                error: (message) => logger.error(message),\n              } as Console,\n              logLevel: asExtismLogLevel(logger.getLogLevel()),\n              enableWasiOutput: true,\n            },\n          ),\n        destroy: (plugin) => plugin.close(),\n      },\n      { min: 1, max: 5 },\n    );\n\n    try {\n      await pool.ready();\n      this.pluginMap.set(key, { pool, label });\n    } catch (error: Error | any) {\n      throw new Error(`Unable to instantiate plugin: ${key}`, { cause: error });\n    }\n  }\n\n  async callMethod<T>({ pluginKey, methodName }: PluginMethod, input: unknown, context?: unknown) {\n    const item = this.pluginMap.get(pluginKey);\n    if (!item) {\n      throw new Error(`No loaded plugin found for ${pluginKey}`);\n    }\n\n    const { pool, label } = item;\n\n    try {\n      const plugin = await pool.acquire();\n      try {\n        const result = await plugin.call(methodName, JSON.stringify(input), context);\n        return (result ? result.json() : result) as T;\n      } finally {\n        await pool.release(plugin);","sourceCodeStart":222,"sourceCodeEnd":258,"githubUrl":"https://github.com/immich-app/immich/blob/e55ac299a4ec7cb372e35dbf2c6c05ee9ce77f6c/server/src/repositories/plugin.repository.ts#L222-L258","documentation":"When loading a plugin, a worker pool is created and awaited via pool.ready(); if the worker fails to initialize (bad code, syntax error, missing dependency inside the plugin, initialization timeout), load() throws 'Unable to instantiate plugin: <key>' with the cause attached. The plugin is not registered in pluginMap and cannot be called.","triggerScenarios":"load(key, path/label) creates a worker pool and pool.ready() rejects or times out — plugin source has a compile/syntax error, throws during top-level init, or a required module inside the plugin is missing.","commonSituations":"Plugin built for a different runtime version; plugin's dependencies not installed in the worker environment; top-level code throwing (bad config read); ESM/CJS module format mismatch; worker resource limits.","solutions":["Inspect the `cause` for the worker's real initialization error (stack trace from the plugin)","Run/compile the plugin standalone to reproduce the init failure","Install missing plugin dependencies and rebuild the plugin for the correct runtime/module format","Fix any top-level throwing code in the plugin entry point"],"exampleFix":"// before (plugin/src/index.ts)\nconst cfg = JSON.parse(process.env.PLUGIN_CFG); // throws at init\n// after\nconst cfg = process.env.PLUGIN_CFG ? JSON.parse(process.env.PLUGIN_CFG) : {};","handlingStrategy":"try-catch","validationCode":"// before load(): smoke-check the plugin module compiles/loads\nawait import(pluginPath); // throws early with the real syntax/resolve error","typeGuard":null,"tryCatchPattern":"try {\n  await pluginRepo.load({ key, label /* ... */ });\n} catch (e) {\n  if (String(e.message).startsWith('Unable to instantiate plugin')) {\n    logger.error(`Plugin ${key} failed to init`, { cause: (e as any).cause });\n    disabledPlugins.add(key); // continue startup without the plugin\n  } else throw e;\n}","preventionTips":["Test plugin workers in CI with the same runtime version as production","Install plugin dependencies inside the plugin's own environment","Avoid throwing top-level code in plugin entry points; defer to explicit init()","Validate the plugin manifest (key, entry path, module format) before load"],"tags":["plugin","worker","initialization"],"backgroundTag":"module-init-failed","analyzedSha":"e55ac299a4ec7cb372e35dbf2c6c05ee9ce77f6c","analyzedAt":"2026-09-15T07:20:19.675Z","contentChangedAt":"2026-09-15T07:20:19.675Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}