github/copilot-sdk · error

Failed to set foreground session

Error message

Failed to set foreground session

What it means

The session.setForeground RPC returned a falsy success flag — the runtime received the request to make the given session the TUI foreground session but rejected it. Typically the sessionId is unknown, the session is not in a state that can be foregrounded, or the TUI runtime does not support the operation.

Solutions

1. Confirm the sessionId was returned by createSession and still exists
2. Ensure the target session is active before setting it foreground
3. Check the runtime version supports session.setForeground; if not, update the runtime

When it happens

Trigger: Thrown at nodejs/src/client.ts:2466 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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

Appendix: source

Thrown at nodejs/src/client.ts:2466

     * @returns A promise that resolves when the session is switched
     * @throws Error if the client is not connected or if the operation fails
     *
     * @example
     * ```typescript
     * // Switch the TUI to display a specific session
     * await client.setForegroundSessionId("session-123");
     * ```
     */
    async setForegroundSessionId(sessionId: string): Promise<void> {
        if (!this.connection) {
            throw new Error("Client not connected");
        }

        const response = await this.connection.sendRequest("session.setForeground", { sessionId });
        const result = response as { success: boolean; error?: string };

        if (!result.success) {
            throw new Error(result.error || "Failed to set foreground session");
        }
    }

    /**
     * Subscribes to a specific session lifecycle event type.
     *
     * Lifecycle events are emitted when sessions are created, deleted, updated,
     * or change foreground/background state (in TUI+server mode).
     *
     * @param eventType - The specific event type to listen for
     * @param handler - A callback function that receives events of the specified type
     * @returns A function that, when called, unsubscribes the handler
     *
     * @example
     * ```typescript
     * // Listen for when a session becomes foreground in TUI
     * const unsubscribe = client.onLifecycle("session.foreground", (event) => {
     *   console.log(`Session ${event.sessionId} is now displayed in TUI`);

View on GitHub (pinned to cd8cf15dc3)