musistudio/claude-code-router · error · Error

Bot Gateway QR start response missing qrCodeUrl.

Error message

Bot Gateway QR start response missing qrCodeUrl.

What it means

After the Bot Gateway SDK's QR auth start ('auth.qr.start') returns, the service extracts the scannable QR URL via qrCodeUrlFromAuth(auth). If the response carries no qrCodeUrl field, login cannot proceed because there is nothing for the user to scan, so the start request is aborted with this error.

Source

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

    if (previous) {
      closeQrClient(previous.client);
    }
    qrSessions.set(sessionId, {
      botConfigId: savedConfig.id,
      client,
      credentials: bot.credentials,
      integrationConfig: bot.integrationConfig,
      integrationId,
      platform: bot.platform,
      stateDir,
      tenantId: bot.tenantId,
      timeoutMs
    });
    registered = true;

    const qrCodeUrl = qrCodeUrlFromAuth(auth);
    if (!qrCodeUrl) {
      throw new Error("Bot Gateway QR start response missing qrCodeUrl.");
    }

    return {
      botConfigId: savedConfig.id,
      expiresAt: stringValue(auth.expiresAt),
      integrationId,
      message: stringValue(auth.message),
      platform: bot.platform,
      qrCodeUrl,
      sessionId,
      stateDir,
      tenantId: bot.tenantId
    };
  } catch (error) {
    if (!registered) {
      closeQrClient(client);
    }
    throw error;

View on GitHub (pinned to 99f24806c6)

Solutions

1. Verify gateway and SDK versions match, restart the bot-gateway process, and retry startBotGatewayQrLogin()
2. Log/inspect the raw auth object returned by auth.qr.start to see which field actually carries the QR URL
3. If the field was renamed, update qrCodeUrlFromAuth() or upgrade @the-next-ai/bot-gateway-sdk to the version the gateway implements
4. Resolve upstream gateway auth errors (account, auth-mode config) before retrying QR login

Example fix

// before
const qrCodeUrl = qrCodeUrlFromAuth(auth);
if (!qrCodeUrl) {
  throw new Error("Bot Gateway QR start response missing qrCodeUrl.");
}

// after — surface the raw response for diagnosis
const qrCodeUrl = qrCodeUrlFromAuth(auth);
if (!qrCodeUrl) {
  throw new Error(`Bot Gateway QR start response missing qrCodeUrl. Response: ${JSON.stringify(auth)}`);
}

function isQrStartAuth(value: unknown): value is { qrCodeUrl: string } {
  return typeof value === "object" && value !== null &&
    typeof (value as { qrCodeUrl?: unknown }).qrCodeUrl === "string" &&
    (value as { qrCodeUrl: string }).qrCodeUrl.length > 0;
}

try {
  const start = await startBotGatewayQrLogin(request);
} catch (error) {
  if (error instanceof Error && error.message.includes("missing qrCodeUrl")) {
    // log gateway/SDK versions and raw exchange; surface a 'QR login unavailable' UI
  } else throw error;
}

When it happens

Trigger: Calling startBotGatewayQrLogin() when the gateway's auth.qr.start response has a missing, empty, or renamed qrCodeUrl field (e.g. qr_code_url or a nested structure), or when the gateway returned an error/declined payload that was treated as a successful auth object.

Common situations: Version mismatch between the bundled @the-next-ai/bot-gateway-sdk and the gateway process; SDK response schema changed across a major bump; WeChat auth unavailable for the account/region so no QR was generated; gateway fell back to a non-QR auth mode.

Related errors

• 微信扫码登录会话不存在，请重新生成二维码。
• Bot Gateway SDK client does not expose request().
• Unable to load @the-next-ai/bot-gateway-sdk. ${errors.join("
• No Bot Gateway conversationRef is configured and no inbound
• No Bot Gateway conversationRef is available for inbound bot

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