{"record":{"id":"9202c755df26be6d","repo":"musistudio/claude-code-router","slug":"unable-to-load-the-next-ai-bot-gateway-sdk-err-9202c7","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":null,"httpStatus":null,"severity":"critical","filePath":"packages/core/src/agents/codex/cli-middleware-runtime.ts","lineNumber":5817,"sourceCode":"  }\n  const bundled = bundledBotGatewaySdkModule();\n  if (bundled) {\n    candidates.push(bundled);\n  }\n  candidates.push(\"@the-next-ai/bot-gateway-sdk\");\n  const errors = [];\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;\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 bundledBotGatewaySdkModule() {\n  const resourcesPath = process[\"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) => fs.existsSync(candidate)) || \"\";\n}\n\nfunction botGatewaySdkImportSpecifier(value) {\n  const trimmed = String(value || \"\").trim();","sourceCodeStart":5799,"sourceCodeEnd":5835,"githubUrl":"https://github.com/musistudio/claude-code-router/blob/99f24806c6a2c660b16e53e95211c517448a6c90/packages/core/src/agents/codex/cli-middleware-runtime.ts#L5799-L5835","documentation":"Thrown when the loader tried every candidate module specifier for @the-next-ai/bot-gateway-sdk and none imported successfully or exposed a createBotGatewayClient export. The error aggregates per-candidate reasons (missing export, import failure) joined with '; ' so you can see exactly why each candidate failed.","triggerScenarios":"Importing/starting the middleware runtime when @the-next-ai/bot-gateway-sdk is not installed, is an incompatible version without createBotGatewayClient, fails to resolve (bad bundling/ESM-CJS interop), or the bundled fallback at __dirname/bot-gateway-sdk/dist/index.js is absent.","commonSituations":"Fresh install where the optional peer dependency was skipped; version mismatch after upgrading the SDK (renamed factory export); Electron/packaged builds where node_modules and process.resourcesPath lookup paths are not bundled correctly; broken dist build of the SDK.","solutions":["Install/align the SDK: npm install @the-next-ai/bot-gateway-sdk at the version required by this package","Read the joined reasons in the message: 'missing createBotGatewayClient export' means version mismatch; an import stack means resolution/bundling — fix accordingly","For packaged apps, ensure bot-gateway-sdk/dist/index.js is included next to the middleware bundle (bundledBotGatewaySdkModule candidates)","If using a bundler, mark @the-next-ai/bot-gateway-sdk as external so runtime resolution works"],"exampleFix":"// before\n// SDK not installed -> Unable to load @the-next-ai/bot-gateway-sdk. ...: missing createBotGatewayClient export\n// after\n$ npm install @the-next-ai/bot-gateway-sdk@^<required-version>","handlingStrategy":"try-catch","validationCode":"try {\n  const sdk = await import('@the-next-ai/bot-gateway-sdk');\n  if (typeof sdk.createBotGatewayClient !== 'function') throw new Error('incompatible SDK version');\n} catch { /* install correct version before starting runtime */ }","typeGuard":"null","tryCatchPattern":"try { runtime = createRuntime(config); } catch (e) { if (e instanceof Error && e.message.startsWith('Unable to load @the-next-ai/bot-gateway-sdk')) { /* surface install/bundling fix, abort startup */ } else throw e; }","preventionTips":["Pin the SDK version in package.json","Add the SDK to bundled resources for packaged apps","Fail fast at startup with a dependency preflight check"],"tags":["dependency","import","bot-gateway-sdk","bundling"],"backgroundTag":"module-not-found","analyzedSha":"99f24806c6a2c660b16e53e95211c517448a6c90","analyzedAt":"2026-08-27T04:11:01.184Z","schemaVersion":2},"datasetVersion":"2026-08-27T08:17:20.692Z"}