{"record":{"id":"6078abafdd50a3d2","repo":"github/copilot-sdk","slug":"server-port-not-available","errorCode":null,"errorMessage":"Server port not available","messagePattern":"Server port not available","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"nodejs/src/client.ts","lineNumber":2960,"sourceCode":"        }\n\n        // Create JSON-RPC connection over stdin/stdout\n        this.messageWriter = new TeardownResilientStreamMessageWriter(process.stdout);\n        this.connection = createMessageConnection(\n            new StreamMessageReader(process.stdin),\n            this.messageWriter\n        );\n\n        this.attachConnectionHandlers();\n        this.connection.listen();\n    }\n\n    /**\n     * Connect to the CLI server via TCP socket\n     */\n    private async connectViaTcp(): Promise<void> {\n        if (!this.runtimePort) {\n            throw new Error(\"Server port not available\");\n        }\n\n        return new Promise((resolve, reject) => {\n            this.socket = new Socket();\n\n            const connectionTimeout = setTimeout(() => {\n                this.socket?.destroy();\n                reject(new Error(\"Timeout connecting to CLI server\"));\n            }, 10000);\n\n            this.socket.connect(this.runtimePort!, this.actualHost, () => {\n                clearTimeout(connectionTimeout);\n                // Create JSON-RPC connection\n                this.messageWriter = new TeardownResilientStreamMessageWriter(this.socket!);\n                this.connection = createMessageConnection(\n                    new StreamMessageReader(this.socket!),\n                    this.messageWriter\n                );","sourceCodeStart":2942,"sourceCodeEnd":2978,"githubUrl":"https://github.com/github/copilot-sdk/blob/cd8cf15dc3f9e762615790aaed0a771a0f392755/nodejs/src/client.ts#L2942-L2978","documentation":"connectViaTcp connects to a CLI server over a TCP socket, but this.runtimePort is unset, so there is no port to dial. The library throws synchronously instead of attempting a connection to an undefined endpoint. It means the server/port discovery step never ran or failed before the TCP connect.","triggerScenarios":"Calling connect() on a TCP-hosted CopilotClient before the runtime server (or its port) has been assigned — server startup failed, port discovery was skipped, or the port was cleared during teardown/restart.","commonSituations":"Server process failed to boot (port allocation failure, crashed binary) before connect(); calling connect() immediately after construction without awaiting the server-start step; reusing a stopped client whose runtimePort was reset.","solutions":["Start the CLI server first and await the step that assigns runtimePort before calling connect().","Check server startup logs for port allocation or bind failures that left runtimePort unset.","Create a fresh client instance if a previous stop() cleared the port, rather than reconnecting on a stale instance.","Verify firewall/localhost binding so the server can actually acquire a port in your environment."],"exampleFix":"// before\nconst client = new CopilotClient({ hosting: 'tcp', ... });\nawait client.connect(); // runtimePort not yet assigned\n\n// after\nconst client = new CopilotClient({ hosting: 'tcp', ... });\nawait client.start(); // boots server, assigns port\nawait client.connect();","handlingStrategy":"try-catch","validationCode":"if (!client.isServerReady?.()) {\n  throw new Error('TCP server not ready: start the runtime before connecting');\n}","typeGuard":null,"tryCatchPattern":"try {\n  await client.start();\n  await client.connect();\n} catch (err) {\n  if (err instanceof Error && err.message === 'Server port not available') {\n    // inspect server startup logs; recreate client and retry start()\n  }\n  throw err;\n}","preventionTips":["Await the server-start step before connect() in TCP mode.","Capture and check server startup logs for bind/port failures.","Add a readiness probe (port reachable) before connecting.","Create a fresh client after stop() instead of reconnecting on a stale port."],"tags":["tcp","network","lifecycle","port"],"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"}