{"record":{"id":"724ed1960484aa4c","repo":"github/copilot-sdk","slug":"timeout-waiting-for-cli-server-to-start","errorCode":null,"errorMessage":"Timeout waiting for CLI server to start","messagePattern":"Timeout waiting for CLI server to start","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"python/copilot/client.py","lineNumber":4496,"sourceCode":"                line_str = line.decode() if isinstance(line, bytes) else line\n                logger.debug(\"[CLI] %s\", line_str.rstrip())\n                match = re.search(r\"listening on port (\\d+)\", line_str, re.IGNORECASE)\n                if match:\n                    self._runtime_port = int(match.group(1))\n                    return\n\n        try:\n            port_wait_start = time.perf_counter()\n            await asyncio.wait_for(read_port(), timeout=10.0)\n            log_timing(\n                logger,\n                logging.DEBUG,\n                \"CopilotClient._start_cli_server TCP port wait complete\",\n                port_wait_start,\n                port=self._runtime_port,\n            )\n        except TimeoutError:\n            raise RuntimeError(\"Timeout waiting for CLI server to start\")\n\n    async def _start_inprocess_ffi(self) -> None:\n        \"\"\"Host the runtime in-process via the native FFI library.\n\n        Loads the native runtime library and opens the FFI JSON-RPC connection.\n\n        Raises:\n            RuntimeError: If the native library is missing or startup fails.\n        \"\"\"\n        assert isinstance(self._connection, InProcessRuntimeConnection)\n        runtime_path = self._inprocess_runtime_path\n        assert runtime_path is not None  # resolved in __init__\n\n        logger.info(\n            \"CopilotClient._start_inprocess_ffi hosting Copilot runtime in-process\",\n            extra={\"runtime_path\": runtime_path, \"runtime_path_source\": self._cli_path_source},\n        )\n","sourceCodeStart":4478,"sourceCodeEnd":4514,"githubUrl":"https://github.com/github/copilot-sdk/blob/cd8cf15dc3f9e762615790aaed0a771a0f392755/python/copilot/client.py#L4478-L4514","documentation":"RuntimeError raised when the TCP port-wait step times out: the CLI process is alive but never printed a 'listening on port N' announcement within the allowed window. The library converts the TimeoutError into this message.","triggerScenarios":"CLI is slow to start (cold start, slow disk/AV scan), prints the announcement in an unexpected format, or hangs at startup so read_port() never matches the port regex before the deadline.","commonSituations":"Slow machines or containers with heavy startup latency; antivirus delaying binary launch; CLI versions whose log line format changed; resource-starved CI runners.","solutions":["Increase the CLI startup timeout in the client configuration if available","Confirm the CLI version prints 'listening on port <n>' (upgrade/downgrade to a compatible version)","Check system resources (CPU, disk, antivirus) that may delay process startup","Enable debug logging to see the lines the CLI actually emits while waiting"],"exampleFix":"// before\nclient = CopilotClient()  # default timeout too short on slow CI\n\n// after\nclient = CopilotClient(cli_start_timeout=120)  # allow more startup time","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try:\n    await client.start()\nexcept RuntimeError as e:\n    if \"Timeout waiting for CLI server to start\" in str(e):\n        raise StartupTimeout(\"CLI did not announce a port in time\") from e","preventionTips":["Configure a generous startup timeout on slow machines/CI","Keep antivirus from scanning the CLI binary on every launch","Pin compatible CLI versions (log-line format drift causes hangs)","Enable SDK debug logging during onboarding to observe startup lines"],"tags":["timeout","startup","tcp","subprocess"],"backgroundTag":"request-timeout","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"}