github/copilot-sdk · error · InvalidOperationException

Cannot connect because TCP host or port are not available

Error message

Cannot connect because TCP host or port are not available

What it means

When the connection mode is TCP, the client connects a Socket to tcpHost:tcpPort. This InvalidOperationException is thrown before connecting if either host or port is null. It guards against attempting a TCP connect with incomplete connection parameters.

Solutions

1. Pass both host and port to the client constructor / connection options when using TCP mode.
2. Verify the CLI was started with the TCP-listening flag and check its logs for the advertised port.
3. Check environment variables (e.g. the port the CLI prints) are propagated to your process.
4. Fall back to stdio mode if you do not manage a TCP server yourself.

Example fix

// before: TCP mode without a port
var client = new CopilotClient(new CopilotClientOptions { Host = "127.0.0.1" });

// after: supply both, or use stdio
var client = new CopilotClient(new CopilotClientOptions { Host = "127.0.0.1", Port = 4242 });
// or: new CopilotClient(); // defaults to stdio

if (string.IsNullOrEmpty(options.Host) || options.Port is null or <= 0)
    throw new ArgumentException("TCP host and port are required for TCP mode");

try { await client.StartAsync(); }
catch (InvalidOperationException ex) when (ex.Message.Contains("TCP host or port"))
{ /* fall back to stdio or reconfigure */ }

When it happens

Trigger: Starting the client in TCP connection mode while tcpHost or tcpPort was not supplied/resolved (e.g. constructor options omitted or the CLI failed to report its listening endpoint).

Common situations: Constructing CopilotClient for an externally-managed CLI server but forgetting to pass host/port; environment variable or config that carries the port not set; CLI started without the flag that makes it listen on TCP.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• TcpConnectionToken must be a non-empty string
• TcpConnectionToken cannot be used with UseStdio = true
• ConnectionToken must be a non-empty string or null.
• Unsupported RuntimeConnection type
• CopilotClient was created with Mode =…

AI-assisted analysis of github/copilot-sdk@cd8cf15dc3 (2026-09-09). Data as JSON: /api/errors/e096027beee451a5. Report an issue: GitHub.

Appendix: source

Thrown at dotnet/src/Client.cs:2652

            {
                inputStream = ffiHost.ReceiveStream;
                outputStream = ffiHost.SendStream;
            }
            else if (_connection is StdioRuntimeConnection)
            {
                if (cliProcess == null)
                {
                    throw new InvalidOperationException("Runtime process not started");
                }

                inputStream = cliProcess.StandardOutput.BaseStream;
                outputStream = cliProcess.StandardInput.BaseStream;
            }
            else
            {
                if (tcpHost is null || tcpPort is null)
                {
                    throw new InvalidOperationException("Cannot connect because TCP host or port are not available");
                }

                var socket = new Socket(SocketType.Stream, ProtocolType.Tcp);
                try
                {
                    var tcpConnectTimestamp = Stopwatch.GetTimestamp();
                    LogConnectingToCliServer(_logger, tcpHost, tcpPort.Value);
                    await socket.ConnectAsync(tcpHost, tcpPort.Value, cancellationToken);
                    LoggingHelpers.LogTiming(_logger, LogLevel.Debug, null,
                        "CopilotClient.ConnectToServerAsync TCP connect complete. Elapsed={Elapsed}, Host={Host}, Port={Port}",
                        tcpConnectTimestamp,
                        tcpHost,
                        tcpPort.Value);
                }
                catch
                {
                    socket.Dispose();
                    throw;

View on GitHub (pinned to cd8cf15dc3)