github/copilot-sdk · error

Invalid auto mode switch request payload

Error message

Invalid auto mode switch request payload

What it means

The auto-mode-switch handler validates only that params exists and params.sessionId is a string; otherwise it throws. This is the minimal gate before resolving the session and forwarding errorCode/retryAfterSeconds.

Solutions

1. Pass a plain object with a string sessionId field alongside errorCode/retryAfterSeconds.
2. Unwrap nested payload levels before calling (params = event.data).
3. Coerce numeric/string ids to string explicitly before invocation.
4. Add a pre-call assertion for the payload shape.

Example fix

// before
await client.handleAutoModeSwitchRequest(err); // err has no sessionId
// after
await client.handleAutoModeSwitchRequest({
  sessionId: String(ctx.sessionId),
  errorCode: err.code,
  retryAfterSeconds: err.retryAfter
});

if (!params || typeof params.sessionId !== "string") {
  throw new TypeError("auto mode switch requires string sessionId");
}

function isAutoModeSwitchParams(p): p is { sessionId: string; errorCode?: unknown; retryAfterSeconds?: number } {
  return typeof p === "object" && p !== null && typeof (p as any).sessionId === "string";
}

try {
  await client.handleAutoModeSwitchRequest(params);
} catch (e) {
  if (e instanceof Error && e.message === "Invalid auto mode switch request payload") {
    // unwrap nested payload and retry once
  }
}

When it happens

Trigger: Invoking the auto-mode-switch request path with params null/undefined, or with sessionId missing/undefined/non-string (number, object, empty via wrong field).

Common situations: Event payload flattened incorrectly so the id sits at params.data.sessionId; retry plumbing built before sessionId was assigned; automated retry loop passing a rate-limit error object as params instead of a structured request.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• Invalid user input request payload
• Invalid exit plan mode request payload
• Invalid hooks invoke payload
• Invalid systemMessage.transform payload
• invalid auto mode switch request payload

AI-assisted analysis of github/copilot-sdk@cd8cf15dc3 (2026-09-09). Data as JSON: /api/errors/b8e7c66fa84c3730. Report an issue: GitHub.

Appendix: source

Thrown at nodejs/src/client.ts:3215

        const session = this.sessions.get(params.sessionId);
        if (!session) {
            throw new Error(`Session not found: ${params.sessionId}`);
        }

        return await session._handleExitPlanModeRequest({
            summary: params.summary,
            planContent: params.planContent,
            actions: params.actions,
            recommendedAction: params.recommendedAction,
        });
    }

    private async handleAutoModeSwitchRequest(
        params: AutoModeSwitchRequest & { sessionId: string }
    ): Promise<{ response: AutoModeSwitchResponse }> {
        if (!params || typeof params.sessionId !== "string") {
            throw new Error("Invalid auto mode switch request payload");
        }

        const session = this.sessions.get(params.sessionId);
        if (!session) {
            throw new Error(`Session not found: ${params.sessionId}`);
        }

        const response = await session._handleAutoModeSwitchRequest({
            errorCode: params.errorCode,
            retryAfterSeconds: params.retryAfterSeconds,
        });
        return { response };
    }

    private async handleHooksInvoke(params: {
        sessionId: string;
        hookType: string;
        input: unknown;

View on GitHub (pinned to cd8cf15dc3)