musistudio/claude-code-router · critical

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

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.

Source

Thrown at packages/core/src/agents/codex/cli-middleware-runtime.ts:5817

  }
  const bundled = bundledBotGatewaySdkModule();
  if (bundled) {
    candidates.push(bundled);
  }
  candidates.push("@the-next-ai/bot-gateway-sdk");
  const errors = [];
  for (const candidate of candidates) {
    try {
      const sdk = await import(botGatewaySdkImportSpecifier(candidate));
      if (sdk && typeof sdk.createBotGatewayClient === "function") {
        return sdk;
      }
      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 bundledBotGatewaySdkModule() {
  const resourcesPath = process["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) => fs.existsSync(candidate)) || "";
}

function botGatewaySdkImportSpecifier(value) {
  const trimmed = String(value || "").trim();

View on GitHub (pinned to 99f24806c6)

Solutions

1. Install/align the SDK: npm install @the-next-ai/bot-gateway-sdk at the version required by this package
2. Read the joined reasons in the message: 'missing createBotGatewayClient export' means version mismatch; an import stack means resolution/bundling — fix accordingly
3. For packaged apps, ensure bot-gateway-sdk/dist/index.js is included next to the middleware bundle (bundledBotGatewaySdkModule candidates)
4. If using a bundler, mark @the-next-ai/bot-gateway-sdk as external so runtime resolution works

Example fix

// before
// SDK not installed -> Unable to load @the-next-ai/bot-gateway-sdk. ...: missing createBotGatewayClient export
// after
$ npm install @the-next-ai/bot-gateway-sdk@^<required-version>

try {
  const sdk = await import('@the-next-ai/bot-gateway-sdk');
  if (typeof sdk.createBotGatewayClient !== 'function') throw new Error('incompatible SDK version');
} catch { /* install correct version before starting runtime */ }

null

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; }

When it happens

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

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

Related errors

• Local agent provider was not found.
• ${candidate.detail || "Local agent login is not importable."
• Chrome login import job was not found: ${jobId}
• browser_chrome_login_import requires domains or an active ht

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