{"record":{"id":"9a47a4638d2a8304","repo":"musistudio/claude-code-router","slug":"unable-to-load-the-next-ai-bot-gateway-sdk-err","errorCode":null,"errorMessage":"Unable to load @the-next-ai/bot-gateway-sdk. ${errors.join(\"; \")}","messagePattern":"Unable to load @the-next-ai/bot-gateway-sdk\\. (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"critical","filePath":"packages/core/src/agents/bot-gateway/qr-login-service.ts","lineNumber":308,"sourceCode":"async function importBotGatewaySdk(): Promise<BotGatewaySdkModule> {\n  const candidates = [\n    process.env.CCR_BOT_GATEWAY_SDK_MODULE,\n    resolveBundledBotGatewaySdkModule(),\n    \"@the-next-ai/bot-gateway-sdk\"\n  ].filter((value): value is string => Boolean(value?.trim()));\n  const errors: string[] = [];\n  for (const candidate of candidates) {\n    try {\n      const sdk = await import(botGatewaySdkImportSpecifier(candidate));\n      if (sdk && typeof sdk.createBotGatewayClient === \"function\") {\n        return sdk as BotGatewaySdkModule;\n      }\n      errors.push(`${candidate}: missing createBotGatewayClient export`);\n    } catch (error) {\n      errors.push(`${candidate}: ${formatError(error)}`);\n    }\n  }\n  throw new Error(`Unable to load @the-next-ai/bot-gateway-sdk. ${errors.join(\"; \")}`);\n}\n\nfunction resolveBundledBotGatewaySdkModule(): string {\n  const resourcesPath = (process as NodeJS.Process & { resourcesPath?: string }).resourcesPath;\n  const candidates = [\n    path.join(__dirname, \"bot-gateway-sdk\", \"dist\", \"index.js\"),\n    ...(resourcesPath\n      ? [\n          path.join(resourcesPath, \"app.asar\", \"dist\", \"main\", \"bot-gateway-sdk\", \"dist\", \"index.js\"),\n          path.join(resourcesPath, \"app\", \"dist\", \"main\", \"bot-gateway-sdk\", \"dist\", \"index.js\")\n        ]\n      : [])\n  ];\n  return candidates.find((candidate) => existsSync(candidate)) ?? \"\";\n}\n\nasync function resolveWeixinQrIntegrationId(\n  client: BotGatewayClientWithRequest,","sourceCodeStart":290,"sourceCodeEnd":326,"githubUrl":"https://github.com/musistudio/claude-code-router/blob/99f24806c6a2c660b16e53e95211c517448a6c90/packages/core/src/agents/bot-gateway/qr-login-service.ts#L290-L326","documentation":"importBotGatewaySdk() tries each candidate location for @the-next-ai/bot-gateway-sdk (installed package, bundled dist next to __dirname, packaged-app resourcesPath). Every failed candidate records a reason; when none load successfully AND export createBotGatewayClient, it throws this aggregate error listing all attempts, which makes it the primary diagnostic for SDK load problems.","triggerScenarios":"All candidate requires fail: package absent from node_modules, bot-gateway-sdk/dist missing from the build output, packaged Electron app lacking the resourcesPath copy, native dependency failing to compile/load, or a loaded module missing the createBotGatewayClient export.","commonSituations":"Fresh clone without building the SDK; electron-builder file filters excluding bot-gateway-sdk; asar packing breaking require of native modules; Node/Electron ABI mismatch with the SDK's native bindings; corrupted or partially installed node_modules.","solutions":["Read the joined candidate list — each entry states the exact path and failure reason (missing module, load error, or missing export)","Run npm install / npm rebuild so node_modules contains @the-next-ai/bot-gateway-sdk with a createBotGatewayClient export","For packaged apps, ensure the bundled bot-gateway-sdk/dist files ship with the build (fix electron-builder files config) and that the resourcesPath candidate resolves","If native bindings fail, rebuild them against the running Electron/Node ABI (electron-rebuild)"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"// Probe candidate SDK paths before relying on importBotGatewaySdk\nimport { existsSync } from \"node:fs\";\nimport path from \"node:path\";\nconst candidates = [\n  path.join(\"node_modules\", \"@the-next-ai\", \"bot-gateway-sdk\", \"dist\", \"index.js\"),\n  path.join(__dirname, \"bot-gateway-sdk\", \"dist\", \"index.js\")\n];\nif (!candidates.some(existsSync)) {\n  throw new Error(\"bot-gateway SDK not found; run npm install / fix packaging\");\n}","typeGuard":null,"tryCatchPattern":"try {\n  const sdk = await loadBotGatewaySdk();\n} catch (error) {\n  if (error instanceof Error && error.message.startsWith(\"Unable to load @the-next-ai/bot-gateway-sdk\")) {\n    // parse the per-candidate reasons; reinstall/rebuild/package the SDK\n  } else throw error;\n}","preventionTips":["Add a smoke test that imports the SDK in both dev and packaged builds","Include bot-gateway-sdk in electron-builder files config explicitly","Run npm rebuild for native deps when the Electron/Node version changes"],"tags":["bot-gateway","module-loading","packaging","electron","native-modules"],"backgroundTag":"module-not-found","analyzedSha":"99f24806c6a2c660b16e53e95211c517448a6c90","analyzedAt":"2026-08-27T04:11:01.184Z","schemaVersion":2},"datasetVersion":"2026-08-27T08:17:20.692Z"}