github/copilot-sdk · error · IOException

Timed out waiting for Copilot CLI to report its TCP…

Error message

Timed out waiting for Copilot CLI to report its TCP listening port.

What it means

Thrown by CopilotClient when the Copilot CLI subprocess fails to report its TCP listening port within the configured startup timeout. The library launches the CLI, pumps its stderr, and waits for a port announcement; if the internal deadline (not user cancellation) elapses, the timeout is converted into a CLI-exited startup failure carrying the buffered stderr. It signals that the runtime process never became reachable.

Solutions

Re-run with debug logging and inspect the buffered stderr attached to the exception for the CLI's last output
Verify the Copilot CLI is installed, on PATH, and at a compatible version (run `copilot --version` manually)
Ensure the CLI authenticates non-interactively (pre-provision token/env credentials so it never blocks on a prompt)
Increase the startup timeout option on CopilotClient if the environment is slow
Retry once; if it recurs, capture the stderr and report against the CLI runtime

Example fix

// before
var client = new CopilotClient(options); // default startup timeout, times out in CI
// after
var client = new CopilotClient(options with { StartupTimeout = TimeSpan.FromMinutes(2) });

Defensive patterns

Strategy: try-catch

Validate before calling

// before connecting (C#)
var version = await Process.RunAsync("copilot", "--version");
if (string.IsNullOrWhiteSpace(version)) throw new InvalidOperationException("Copilot CLI not installed or not on PATH");

Try / catch

try
{
    await client.StartAsync(cts.Token);
}
catch (Exception ex) when (ex.Message.Contains("Timed out waiting for Copilot CLI to report its TCP listening port"))
{
    logger.LogError(ex, "CLI startup timeout; buffered stderr: {Stderr}", ex.Data["stderr"]);
    // retry once with a longer timeout, or surface config guidance
}

Prevention

Pin and verify the Copilot CLI version before starting the client
Provision credentials via env/token so the CLI never blocks on an interactive prompt
Set a generous startup timeout in CI/container environments
Capture stderr pump output on every start attempt for diagnosis

When it happens

Trigger: Calling a CopilotClient connect/start API when the CLI process starts but never announces its TCP listening port before the internal CTS deadline fires; the CLI hangs at startup (blocked on an auth prompt or update check); a slow machine/container makes startup exceed the timeout; the CLI crashes without emitting the port line (buffered stderr is attached to the exception).

Common situations: Stale or incompatible copilot-cli version whose startup output changed; corporate proxy or expired credentials causing an interactive auth prompt in a non-TTY environment; resource-starved CI runners; antivirus or sandbox policies delaying process spawn.

Understand the failure class

Background: Request timed out: what client-side request timeouts mean across libraries (Request timed out, TIMED_OUT, APITimeoutError) — this error's family across 39 libraries.

Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

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

Appendix: source

Thrown at dotnet/src/Client.cs:2450

                                detectedLocalhostTcpPort.Value);
                            break;
                        }
                    }

                    if (detectedLocalhostTcpPort is null)
                    {
                        // The CLI's stdout closed (process exited). Drain stderr
                        // before throwing so the surfaced exception includes the
                        // final diagnostic lines.
                        try { await stderrPump.Completion.WaitAsync(s_stderrPumpShutdownTimeout, CancellationToken.None); }
                        catch (TimeoutException) { /* best-effort: include whatever was captured */ }
                        catch (Exception ex) { logger.LogDebug(ex, "Runtime stderr pump faulted while draining"); }
                        throw CreateCliExitedException("Runtime process exited unexpectedly", stderrPump.Buffer);
                    }
                }
                catch (OperationCanceledException) when (!cancellationToken.IsCancellationRequested && cts.IsCancellationRequested)
                {
                    throw CreateCliExitedException("Timed out waiting for Copilot CLI to report its TCP listening port.", stderrPump.Buffer);
                }
            }

            return (cliProcess, detectedLocalhostTcpPort, stderrPump);
        }
        catch
        {
            await CleanupCliProcessAsync(cliProcess, stderrPump, errors: null, logger);

            throw;
        }
    }

    private static string? GetBundledCliPath(out string searchedPath)
    {
        return GetBundledNativePath(OperatingSystem.IsWindows() ? "copilot.exe" : "copilot", out searchedPath);
    }

View on GitHub (pinned to cd8cf15dc3)