{"record":{"id":"2e2589c353126a1a","repo":"github/copilot-sdk","slug":"failed-to-set-foreground-session-error","errorCode":null,"errorMessage":"Failed to set foreground session: {error}","messagePattern":"Failed to set foreground session: (.+?)","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"python/copilot/client.py","lineNumber":3996,"sourceCode":"\n        Args:\n            session_id: The ID of the session to display in the TUI.\n\n        Raises:\n            RuntimeError: If the client is not connected or the operation fails.\n\n        Example:\n            >>> await client.set_foreground_session_id(\"session-123\")\n        \"\"\"\n        if not self._client:\n            raise RuntimeError(\"Client not connected\")\n\n        response = await self._client.request(\"session.setForeground\", {\"sessionId\": session_id})\n\n        success = response.get(\"success\", False)\n        if not success:\n            error = response.get(\"error\", \"Unknown error\")\n            raise RuntimeError(f\"Failed to set foreground session: {error}\")\n\n    @overload\n    def on_lifecycle(self, handler: SessionLifecycleHandler, /) -> HandlerUnsubcribe:\n        pass\n\n    @overload\n    def on_lifecycle(\n        self, event_type: SessionLifecycleEventType, /, handler: SessionLifecycleHandler\n    ) -> HandlerUnsubcribe:\n        pass\n\n    def on_lifecycle(\n        self,\n        event_type_or_handler: SessionLifecycleEventType | SessionLifecycleHandler,\n        /,\n        handler: SessionLifecycleHandler | None = None,\n    ) -> HandlerUnsubcribe:\n        \"\"\"","sourceCodeStart":3978,"sourceCodeEnd":4014,"githubUrl":"https://github.com/github/copilot-sdk/blob/cd8cf15dc3f9e762615790aaed0a771a0f392755/python/copilot/client.py#L3978-L4014","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Read the server error in the message and address it (usually an unknown/invalid session ID)","Verify the session ID exists on the same server instance before switching","Only use set_foreground_session_id when the CLI is running with a TUI that can display sessions","Catch RuntimeError and fall back gracefully when foreground control is unavailable"],"exampleFix":"// before\nawait client.set_foreground_session_id(other_sid)\n// after\ntry:\n    await client.set_foreground_session_id(other_sid)\nexcept RuntimeError as e:\n    logging.warning(\"could not set foreground session: %s\", e)","handlingStrategy":"try-catch","validationCode":"live = await client.get_last_session_id()\nif session_id == live:\n    await client.set_foreground_session_id(session_id)","typeGuard":null,"tryCatchPattern":"try:\n    await client.set_foreground_session_id(session_id)\nexcept RuntimeError as e:\n    logging.warning(\"set foreground failed: %s\", e)  # non-fatal fallback","preventionTips":["Only switch to sessions that exist on the current server instance","Expect foreground switching to fail in headless mode; treat as optional","Check the server error text in the exception for the precise cause"],"tags":["runtime-error","session-management","rpc","python"],"backgroundTag":"api-error-response","analyzedSha":"cd8cf15dc3f9e762615790aaed0a771a0f392755","analyzedAt":"2026-09-09T18:32:31.973Z","contentChangedAt":"2026-09-09T18:32:31.973Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}