github/copilot-sdk · error · RuntimeException

Failed to set foreground session

Error message

Failed to set foreground session

What it means

setForegroundSessionId invokes session.setForeground; if the server reports success=false, the client throws RuntimeException with the server's error message, or the generic "Failed to set foreground session" when no error detail was provided.

Solutions

1. Verify the sessionId belongs to a live session in this client (client.sessions map) before calling
2. Handle the failed future and inspect response.error() for the server's reason
3. Re-create the session if its id is no longer valid, then set foreground on the new id

Example fix

// before
client.setForegroundSessionId(staleId).join();
// after
if (client.getSession(staleId) != null) {
    client.setForegroundSessionId(staleId).join();
}

if (!isLiveSession(client, sessionId)) { return; }

client.setForegroundSessionId(id)
    .exceptionally(ex -> {
        log.warn("setForeground failed for {}: {}", id, ex.getMessage());
        return null;
    });

When it happens

Trigger: Calling setForegroundSessionId with a sessionId the server does not recognize or cannot make foreground; response.success() false in SetForegroundSessionResponse.

Common situations: Setting foreground on a session that was already deleted/expired; id from a different client instance; race with session termination.

Related errors

• {response.Error ?? "Failed to set foreground session"}
• No session found for sessionId
• session.create response did not include a sessionId
• session.create returned sessionId
• Failed to delete session

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

Appendix: source

Thrown at java/sdk/src/main/java/com/github/copilot/CopilotClient.java:1707

    /**
     * Requests the TUI to switch to displaying the specified session.
     * <p>
     * This is only available when connecting to a server running in TUI+server mode
     * (--ui-server).
     *
     * @param sessionId
     *            the ID of the session to display in the TUI
     * @return a future that completes when the operation is done
     * @throws RuntimeException
     *             if the operation fails
     */
    public CompletableFuture<Void> setForegroundSessionId(String sessionId) {
        return ensureConnected().thenCompose(connection -> connection.rpc
                .invoke("session.setForeground", new com.github.copilot.rpc.SetForegroundSessionRequest(sessionId),
                        com.github.copilot.rpc.SetForegroundSessionResponse.class)
                .thenAccept(response -> {
                    if (!response.success()) {
                        throw new RuntimeException(
                                response.error() != null ? response.error() : "Failed to set foreground session");
                    }
                }));
    }

    /**
     * Subscribes to all session lifecycle events.
     * <p>
     * Lifecycle events are emitted when sessions are created, deleted, updated, or
     * change foreground/background state (in TUI+server mode).
     *
     * @param handler
     *            a callback that receives lifecycle events
     * @return an AutoCloseable that, when closed, unsubscribes the handler
     */
    public AutoCloseable onLifecycle(SessionLifecycleHandler handler) {
        return lifecycleManager.subscribe(handler);
    }

View on GitHub (pinned to cd8cf15dc3)