{"record":{"id":"fd1bb591e0f10657","repo":"github/copilot-sdk","slug":"server-port-not-available-fd1bb5","errorCode":null,"errorMessage":"Server port not available","messagePattern":"Server port not available","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"python/copilot/client.py","lineNumber":4646,"sourceCode":"        )\n        register_client_session_api_handlers(self._client, self._get_client_session_handlers)\n        self._register_client_global_handlers()\n\n        # Start listening for messages\n        loop = asyncio.get_running_loop()\n        self._client.start(loop)\n\n    async def _connect_via_tcp(self) -> None:\n        \"\"\"\n        Connect to the CLI server via TCP socket.\n\n        Creates a TCP connection to the server at the configured host and port.\n\n        Raises:\n            RuntimeError: If the server port is not available or connection fails.\n        \"\"\"\n        if not self._runtime_port:\n            raise RuntimeError(\"Server port not available\")\n\n        # Create a TCP socket connection with timeout. create_connection resolves\n        # both IPv4 and IPv6 addresses instead of forcing AF_INET.\n        import socket\n\n        # Connection timeout constant\n        TCP_CONNECTION_TIMEOUT = 10  # seconds\n\n        try:\n            tcp_connect_start = time.perf_counter()\n            logger.info(\n                \"CopilotClient._connect_via_tcp connecting to CLI server\",\n                extra={\"host\": self._actual_host, \"port\": self._runtime_port},\n            )\n            sock = socket.create_connection(\n                (self._actual_host, self._runtime_port), timeout=TCP_CONNECTION_TIMEOUT\n            )\n            sock.settimeout(None)  # Remove timeout after connection","sourceCodeStart":4628,"sourceCodeEnd":4664,"githubUrl":"https://github.com/github/copilot-sdk/blob/cd8cf15dc3f9e762615790aaed0a771a0f392755/python/copilot/client.py#L4628-L4664","documentation":"RuntimeError raised by CopilotClient._connect_via_tcp when the runtime port is missing or unknown, so there is no host:port endpoint to dial. Per the method's docstring it fires when the server port is not available or the connection fails; typically the spawned CLI never reported its listening port during startup.","triggerScenarios":"Calling _connect_via_tcp() before the port-announcement wait completed, after TCP startup failed to set _runtime_port, or when configured for a mode (stdio/FFI) that never sets a runtime port.","commonSituations":"Mixing transports: spawning the CLI in stdio mode then connecting via TCP; skipping the port wait step; a previous startup error left _runtime_port unset; manually constructing the client and calling connect internals out of order.","solutions":["Use the normal start/connect flow so the port announcement is awaited before TCP connect","If connecting to an external server, configure host/port explicitly instead of relying on the announced port","Verify the client is not in stdio/FFI mode when calling the TCP connect path","Recover from failed startups by creating a fresh client instance"],"exampleFix":"// before\nawait client._connect_via_tcp()  # _runtime_port never set -> RuntimeError\n\n// after\nawait client.start()  # waits for 'listening on port N', sets _runtime_port\nawait client._connect_via_tcp()","handlingStrategy":"validation","validationCode":"if not getattr(client, \"_runtime_port\", None):\n    await client.start()  # ensure port announcement completed first","typeGuard":"def has_port(client) -> bool:\n    return bool(getattr(client, \"_runtime_port\", 0))","tryCatchPattern":"try:\n    await client._connect_via_tcp()\nexcept RuntimeError as e:\n    if \"Server port not available\" in str(e):\n        await client.start()\n        await client._connect_via_tcp()\n    else:\n        raise","preventionTips":["Always run the full startup flow before TCP connect","Don't mix stdio/FFI mode with the TCP connect path","Provide an explicit host/port when connecting to an external server","Recreate the client after failed startups instead of partial reconnects"],"tags":["tcp","lifecycle","config"],"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"}