{"record":{"id":"afef97e6b611580b","repo":"github/copilot-sdk","slug":"server-port-not-available-afef97","errorCode":null,"errorMessage":"server port not available","messagePattern":"server port not available","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"go/client.go","lineNumber":2435,"sourceCode":"\t\tclose(done)\n\t}()\n}\n\n// connectToServer establishes a connection to the server.\nfunc (c *Client) connectToServer(ctx context.Context) error {\n\tif c.useStdio || c.useInProcess {\n\t\t// Already connected: stdio in startCLIServer, FFI streams in startInProcess.\n\t\treturn nil\n\t}\n\n\t// Connect via TCP\n\treturn c.connectViaTCP(ctx)\n}\n\n// connectViaTCP connects to the CLI server via TCP socket.\nfunc (c *Client) connectViaTCP(ctx context.Context) error {\n\tif c.actualPort == 0 {\n\t\treturn fmt.Errorf(\"server port not available\")\n\t}\n\n\t// Merge a 10-second timeout with the caller's context so whichever\n\t// deadline comes first wins.\n\taddress := net.JoinHostPort(c.actualHost, fmt.Sprintf(\"%d\", c.actualPort))\n\tdialCtx, cancel := context.WithTimeout(ctx, 10*time.Second)\n\tdefer cancel()\n\tvar dialer net.Dialer\n\tconn, err := dialer.DialContext(dialCtx, \"tcp\", address)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"failed to connect to CLI server at %s: %w\", address, err)\n\t}\n\n\tc.conn = conn\n\n\t// Create JSON-RPC client with the connection\n\tc.client = jsonrpc2.NewClient(conn, conn)\n\tif c.processDone != nil {","sourceCodeStart":2417,"sourceCodeEnd":2453,"githubUrl":"https://github.com/github/copilot-sdk/blob/cd8cf15dc3f9e762615790aaed0a771a0f392755/go/client.go#L2417-L2453","documentation":"Returned by connectViaTCP when the Client was configured for TCP transport but the actual server port is still 0, i.e. no port was discovered or provided. The client cannot dial a TCP endpoint without a port, so it fails fast before attempting a connection.","triggerScenarios":"Calling Client connect logic with TCP transport when the CLI server never reported its port (actualPort == 0): the server failed to start listening, the port discovery step was skipped or failed, or no port was passed in configuration.","commonSituations":"CLI binary too old to report its port; server startup failed before binding a socket; configuration omitted the port while forcing TCP; race where connect is called before the server's port file/announcement is ready.","solutions":["Ensure the CLI server is started first and its port is captured/assigned to the client configuration before connecting.","Pass an explicit port in the client options if the server's port is known and static.","Upgrade the CLI to a version that announces its listening port.","Confirm the transport mode matches how the CLI was launched (stdio vs TCP)."],"exampleFix":"// before\nc := client.New(client.WithTransport(\"tcp\")) // port never set\n\n// after\nc := client.New(client.WithTransport(\"tcp\"), client.WithPort(cliServerPort)) // port from launched server","handlingStrategy":"validation","validationCode":"if cfg.Transport == \"tcp\" && cfg.Port == 0 {\n    return fmt.Errorf(\"tcp transport requires an explicit or discovered port\")\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always start/discover the CLI server before constructing the TCP client.","Pass an explicit port when the server's port announcement is unreliable.","Check CLI version supports port announcement."],"tags":["network","tcp","configuration","go"],"backgroundTag":"missing-config-value","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"}