{"record":{"id":"e31f90036d2ea72a","repo":"github/copilot-sdk","slug":"timed-out-waiting-for-copilot-cli-to-report-its-tc","errorCode":null,"errorMessage":"Timed out waiting for Copilot CLI to report its TCP listening port.","messagePattern":"Timed out waiting for Copilot CLI to report its TCP listening port\\.","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"dotnet/src/Client.cs","lineNumber":2450,"sourceCode":"                                detectedLocalhostTcpPort.Value);\n                            break;\n                        }\n                    }\n\n                    if (detectedLocalhostTcpPort is null)\n                    {\n                        // The CLI's stdout closed (process exited). Drain stderr\n                        // before throwing so the surfaced exception includes the\n                        // final diagnostic lines.\n                        try { await stderrPump.Completion.WaitAsync(s_stderrPumpShutdownTimeout, CancellationToken.None); }\n                        catch (TimeoutException) { /* best-effort: include whatever was captured */ }\n                        catch (Exception ex) { logger.LogDebug(ex, \"Runtime stderr pump faulted while draining\"); }\n                        throw CreateCliExitedException(\"Runtime process exited unexpectedly\", stderrPump.Buffer);\n                    }\n                }\n                catch (OperationCanceledException) when (!cancellationToken.IsCancellationRequested && cts.IsCancellationRequested)\n                {\n                    throw CreateCliExitedException(\"Timed out waiting for Copilot CLI to report its TCP listening port.\", stderrPump.Buffer);\n                }\n            }\n\n            return (cliProcess, detectedLocalhostTcpPort, stderrPump);\n        }\n        catch\n        {\n            await CleanupCliProcessAsync(cliProcess, stderrPump, errors: null, logger);\n\n            throw;\n        }\n    }\n\n    private static string? GetBundledCliPath(out string searchedPath)\n    {\n        return GetBundledNativePath(OperatingSystem.IsWindows() ? \"copilot.exe\" : \"copilot\", out searchedPath);\n    }\n","sourceCodeStart":2432,"sourceCodeEnd":2468,"githubUrl":"https://github.com/github/copilot-sdk/blob/cd8cf15dc3f9e762615790aaed0a771a0f392755/dotnet/src/Client.cs#L2432-L2468","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","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"],"exampleFix":"// before\nvar client = new CopilotClient(options); // default startup timeout, times out in CI\n// after\nvar client = new CopilotClient(options with { StartupTimeout = TimeSpan.FromMinutes(2) });","handlingStrategy":"try-catch","validationCode":"// before connecting (C#)\nvar version = await Process.RunAsync(\"copilot\", \"--version\");\nif (string.IsNullOrWhiteSpace(version)) throw new InvalidOperationException(\"Copilot CLI not installed or not on PATH\");","typeGuard":null,"tryCatchPattern":"try\n{\n    await client.StartAsync(cts.Token);\n}\ncatch (Exception ex) when (ex.Message.Contains(\"Timed out waiting for Copilot CLI to report its TCP listening port\"))\n{\n    logger.LogError(ex, \"CLI startup timeout; buffered stderr: {Stderr}\", ex.Data[\"stderr\"]);\n    // retry once with a longer timeout, or surface config guidance\n}","preventionTips":["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"],"tags":["process-startup","timeout","cli","network"],"backgroundTag":"request-timeout","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"}