github/copilot-sdk · error · RuntimeError

Failed to set foreground session

Error message

Failed to set foreground session: {error}

What it means

After sending 'session.setForeground', the client checks response success. If the server returns success=false, this RuntimeError is raised carrying the server's error string. Unlike error 423, the client WAS connected; the server rejected the operation.

Solutions

1. Read the server error in the message and address it (usually an unknown/invalid session ID)
2. Verify the session ID exists on the same server instance before switching
3. Only use set_foreground_session_id when the CLI is running with a TUI that can display sessions
4. Catch RuntimeError and fall back gracefully when foreground control is unavailable

Example fix

// before
await client.set_foreground_session_id(other_sid)
// after
try:
    await client.set_foreground_session_id(other_sid)
except RuntimeError as e:
    logging.warning("could not set foreground session: %s", e)

live = await client.get_last_session_id()
if session_id == live:
    await client.set_foreground_session_id(session_id)

try:
    await client.set_foreground_session_id(session_id)
except RuntimeError as e:
    logging.warning("set foreground failed: %s", e)  # non-fatal fallback

When it happens

Trigger: Calling await client.set_foreground_session_id(session_id) with a session ID unknown to the server, or when the server cannot switch the TUI's foreground session and returns an error field.

Common situations: Setting foreground to a session that has ended or was created in a different server process; running headless (no TUI) where foreground switching is meaningless.

Related errors

• Failed to delete session
• Client is not connected. Call start() first.
• str(e)
• Invalid entry '*': there is no bare wildcard. Use one or…
• Client is not connected. Call start() first.

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

Appendix: source

Thrown at python/copilot/client.py:3996

        Args:
            session_id: The ID of the session to display in the TUI.

        Raises:
            RuntimeError: If the client is not connected or the operation fails.

        Example:
            >>> await client.set_foreground_session_id("session-123")
        """
        if not self._client:
            raise RuntimeError("Client not connected")

        response = await self._client.request("session.setForeground", {"sessionId": session_id})

        success = response.get("success", False)
        if not success:
            error = response.get("error", "Unknown error")
            raise RuntimeError(f"Failed to set foreground session: {error}")

    @overload
    def on_lifecycle(self, handler: SessionLifecycleHandler, /) -> HandlerUnsubcribe:
        pass

    @overload
    def on_lifecycle(
        self, event_type: SessionLifecycleEventType, /, handler: SessionLifecycleHandler
    ) -> HandlerUnsubcribe:
        pass

    def on_lifecycle(
        self,
        event_type_or_handler: SessionLifecycleEventType | SessionLifecycleHandler,
        /,
        handler: SessionLifecycleHandler | None = None,
    ) -> HandlerUnsubcribe:
        """

View on GitHub (pinned to cd8cf15dc3)