{"record":{"id":"54a1e161900f668d","repo":"github/copilot-sdk","slug":"str-e","errorCode":null,"errorMessage":"str(e)","messagePattern":"str\\(e\\)","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"python/copilot/client.py","lineNumber":2011,"sourceCode":"\n            self._state = \"connected\"\n            log_timing(\n                logger,\n                logging.DEBUG,\n                \"CopilotClient.start complete\",\n                start_time,\n            )\n        except ProcessExitedError as e:\n            # Process exited with error - reraise as RuntimeError with stderr\n            self._state = \"error\"\n            log_timing(\n                logger,\n                logging.WARNING,\n                \"CopilotClient.start failed\",\n                start_time,\n                exc_info=True,\n            )\n            raise RuntimeError(str(e)) from None\n        except Exception as e:\n            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()","sourceCodeStart":1993,"sourceCodeEnd":2029,"githubUrl":"https://github.com/github/copilot-sdk/blob/cd8cf15dc3f9e762615790aaed0a771a0f392755/python/copilot/client.py#L1993-L2029","documentation":"When CopilotClient.start() fails, the library logs the failure, sets internal state to 'error', and re-raises as `RuntimeError(str(e)) from None` — deliberately suppressing the original traceback/exception type. Developers see only the stringified underlying error, which can make the root cause (process spawn failure, binary missing, handshake timeout, etc.) harder to trace.","triggerScenarios":"Any failure inside start(): the Copilot CLI subprocess fails to spawn or exits during startup, the handshake/connection to the CLI fails, or an expected startup exception type (the `except` clause above the generic handler) is raised.","commonSituations":"Copilot CLI binary not installed or not on PATH; wrong CLI path configured; permission denied executing the binary; CLI crashes immediately due to bad arguments or version mismatch.","solutions":["Read the RuntimeError message — it contains the underlying cause string.","Enable logging at WARNING/DEBUG for 'CopilotClient.start failed' (log_timing output includes exc_info).","Verify the CLI binary path/availability manually before calling start().","Catch RuntimeError around start() and, if needed, inspect the full chain via logs since `from None` hides the original exception."],"exampleFix":"// before\nawait client.start()  # bare RuntimeError, no chained traceback\n// after\ntry:\n    await client.start()\nexcept RuntimeError as e:\n    logging.getLogger(__name__).error(\"Copilot startup failed: %s\", e)\n    raise","handlingStrategy":"try-catch","validationCode":"import shutil\nif shutil.which(cli_path) is None:\n    raise FileNotFoundError(f\"Copilot CLI not found: {cli_path}\")","typeGuard":null,"tryCatchPattern":"try:\n    await client.start()\nexcept RuntimeError as e:\n    logger.error(\"CopilotClient.start failed: %s\", e)\n    raise StartupError(str(e)) from e","preventionTips":["Verify the CLI binary exists and is executable before start()","Enable library logging (WARNING+) to capture the underlying cause","Pin a compatible CLI version in your deployment","Wrap start() in app-level startup checks that fail with clear messages"],"tags":["python","startup","subprocess","runtime-error"],"backgroundTag":"invalid-state-transition","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"}