musistudio/claude-code-router · critical · Error

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

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.

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)

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

• ZCode profiles can only open the app; agent arguments are no
• Claude App profiles do not support agent arguments.
• Failed to open Claude App: ${spawnError}
• Failed to open ZCode App: ${spawnError}
• Bot Gateway QR start response missing qrCodeUrl.

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