{"record":{"id":"7dffe8fc6f9803df","repo":"github/copilot-sdk","slug":"process-exit-error-from-get-process-exit-error","errorCode":null,"errorMessage":"{process exit error from _get_process_exit_error()}","messagePattern":"\\{process exit error from _get_process_exit_error\\(\\)\\}","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"python/copilot/client.py","lineNumber":2031,"sourceCode":"            self._state = \"error\"\n            log_timing(\n                logger,\n                logging.WARNING,\n                \"CopilotClient.start failed\",\n                start_time,\n                exc_info=True,\n            )\n            # Check if process exited and capture any remaining stderr\n            process = self._cli_process if self._cli_process is not None else self._process\n            if process and hasattr(process, \"poll\"):\n                if isinstance(e, BrokenPipeError) and process.poll() is None:\n                    try:\n                        await asyncio.to_thread(process.wait, timeout=1.0)\n                    except subprocess.TimeoutExpired:\n                        pass\n                return_code = process.poll()\n                if return_code is not None and self._client:\n                    raise RuntimeError(self._client._get_process_exit_error()) from e\n            raise\n\n    async def stop(self) -> None:\n        \"\"\"\n        Stop the CLI server and close all active sessions.\n\n        This method performs graceful cleanup:\n        1. Closes all active sessions (releases in-memory resources)\n        2. Requests runtime shutdown for SDK-owned CLI processes\n        3. Closes the JSON-RPC connection\n        4. Terminates the CLI server process (if spawned by this client)\n\n        Note: session data on disk is preserved, so sessions can be resumed\n        later. To permanently remove session data before stopping, call\n        :meth:`delete_session` for each session first.\n\n        Raises:\n            ExceptionGroup[StopError]: If any errors occurred during cleanup.","sourceCodeStart":2013,"sourceCodeEnd":2049,"githubUrl":"https://github.com/github/copilot-sdk/blob/cd8cf15dc3f9e762615790aaed0a771a0f392755/python/copilot/client.py#L2013-L2049","documentation":"During start(), if an exception occurs while waiting for the CLI process and the process has already exited (non-None return code), the library re-raises RuntimeError with the message produced by `_get_process_exit_error()`, which describes the process's exit code and captured stderr. This turns a generic startup failure into a diagnostic about why the CLI subprocess died.","triggerScenarios":"The Copilot CLI process terminates during start() — bad CLI arguments, missing/unreadable binary, crash on launch, port conflicts — while the client is waiting for it to become ready.","commonSituations":"Outdated or incompatible CLI version; invalid flags passed through to the CLI; environment missing (e.g. no auth/telemetry config the CLI requires); the CLI binary failing immediately on an unsupported platform.","solutions":["Read the message: it includes the CLI exit code and stderr output — fix the underlying process error it names.","Verify the installed Copilot CLI version is compatible with this client library.","Run the CLI command manually with the same arguments to reproduce and see the error directly.","Check file permissions and PATH resolution for the CLI binary."],"exampleFix":"// before\nawait client.start()  # RuntimeError with process exit details\n// after\ntry:\n    await client.start()\nexcept RuntimeError as e:\n    print(f\"CLI failed to start: {e}\")  # shows exit code + stderr\n    raise","handlingStrategy":"try-catch","validationCode":"proc = await asyncio.create_subprocess_exec(cli_path, ...)\nawait asyncio.sleep(0.2)\nif proc.returncode is not None:\n    raise RuntimeError(f\"CLI exits immediately with code {proc.returncode}\")","typeGuard":null,"tryCatchPattern":"try:\n    await client.start()\nexcept RuntimeError as e:\n    # message includes CLI exit code and stderr from _get_process_exit_error()\n    logger.error(\"CLI process died during startup: %s\", e)\n    raise","preventionTips":["Run the CLI manually with the same flags to verify it starts","Keep the CLI version compatible with the client library","Check binary permissions and PATH resolution","Capture CLI stderr in logs for diagnosis"],"tags":["python","subprocess","process-exit","startup"],"backgroundTag":"connection-refused","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"}