musistudio/claude-code-router · critical · Error

Unable to load @the-next-ai/bot-gateway-sdk.

Error message

Unable to load @the-next-ai/bot-gateway-sdk. ${errors.join("; ")}

What it means

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.

Solutions

1. Read the joined candidate list — each entry states the exact path and failure reason (missing module, load error, or missing export)
2. Run npm install / npm rebuild so node_modules contains @the-next-ai/bot-gateway-sdk with a createBotGatewayClient export
3. 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
4. If native bindings fail, rebuild them against the running Electron/Node ABI (electron-rebuild)

// Probe candidate SDK paths before relying on importBotGatewaySdk
import { existsSync } from "node:fs";
import path from "node:path";
const candidates = [
  path.join("node_modules", "@the-next-ai", "bot-gateway-sdk", "dist", "index.js"),
  path.join(__dirname, "bot-gateway-sdk", "dist", "index.js")
];
if (!candidates.some(existsSync)) {
  throw new Error("bot-gateway SDK not found; run npm install / fix packaging");
}

try {
  const sdk = await loadBotGatewaySdk();
} catch (error) {
  if (error instanceof Error && error.message.startsWith("Unable to load @the-next-ai/bot-gateway-sdk")) {
    // parse the per-candidate reasons; reinstall/rebuild/package the SDK
  } else throw error;
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Bot Gateway QR start response missing qrCodeUrl.
• Bot Gateway SDK client does not expose request().
• Claude App profiles do not support agent arguments.
• Custom router does not export a function
• [deep-link] Failed to register

AI-assisted analysis of musistudio/claude-code-router@99f24806c6 (2026-08-27). Data as JSON: /api/errors/9a47a4638d2a8304. Report an issue: GitHub.

Appendix: source

Thrown at packages/core/src/agents/bot-gateway/qr-login-service.ts:308

async function importBotGatewaySdk(): Promise<BotGatewaySdkModule> {
  const candidates = [
    process.env.CCR_BOT_GATEWAY_SDK_MODULE,
    resolveBundledBotGatewaySdkModule(),
    "@the-next-ai/bot-gateway-sdk"
  ].filter((value): value is string => Boolean(value?.trim()));
  const errors: string[] = [];
  for (const candidate of candidates) {
    try {
      const sdk = await import(botGatewaySdkImportSpecifier(candidate));
      if (sdk && typeof sdk.createBotGatewayClient === "function") {
        return sdk as BotGatewaySdkModule;
      }
      errors.push(`${candidate}: missing createBotGatewayClient export`);
    } catch (error) {
      errors.push(`${candidate}: ${formatError(error)}`);
    }
  }
  throw new Error(`Unable to load @the-next-ai/bot-gateway-sdk. ${errors.join("; ")}`);
}

function resolveBundledBotGatewaySdkModule(): string {
  const resourcesPath = (process as NodeJS.Process & { resourcesPath?: string }).resourcesPath;
  const candidates = [
    path.join(__dirname, "bot-gateway-sdk", "dist", "index.js"),
    ...(resourcesPath
      ? [
          path.join(resourcesPath, "app.asar", "dist", "main", "bot-gateway-sdk", "dist", "index.js"),
          path.join(resourcesPath, "app", "dist", "main", "bot-gateway-sdk", "dist", "index.js")
        ]
      : [])
  ];
  return candidates.find((candidate) => existsSync(candidate)) ?? "";
}

async function resolveWeixinQrIntegrationId(
  client: BotGatewayClientWithRequest,

View on GitHub (pinned to 99f24806c6)