{"record":{"id":"824e7db37b069301","repo":"github/copilot-sdk","slug":"runtime-process-exited-unexpectedly","errorCode":null,"errorMessage":"Runtime process exited unexpectedly","messagePattern":"Runtime process exited unexpectedly","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"critical","filePath":"dotnet/src/Client.cs","lineNumber":2445,"sourceCode":"                        {\n                            detectedLocalhostTcpPort = int.Parse(match.Groups[1].Value, CultureInfo.InvariantCulture);\n                            LoggingHelpers.LogTiming(logger, LogLevel.Debug, null,\n                                \"CopilotClient.StartCliServerAsync TCP port wait complete. Elapsed={Elapsed}, Port={Port}\",\n                                portWaitTimestamp,\n                                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","sourceCodeStart":2427,"sourceCodeEnd":2463,"githubUrl":"https://github.com/github/copilot-sdk/blob/cd8cf15dc3f9e762615790aaed0a771a0f392755/dotnet/src/Client.cs#L2427-L2463","documentation":"During CopilotClient startup, the client waits for the CLI runtime process to report its TCP listening port. If the CLI's stdout closes — meaning the process exited before announcing a port — the client drains captured stderr (best-effort, with a timeout) and throws an exception including those final diagnostic lines so the failure is actionable.","triggerScenarios":"The CLI binary crashes or exits during startup: bad config, unsupported Node/CLI version, port/permission issues, corrupted install, or stdout closed unexpectedly before the port handshake.","commonSituations":"Missing or invalid Copilot CLI configuration; CLI not installed or wrong version for the SDK; environment issues (PATH, permissions, corporate proxy); the CLI writing errors to stderr and dying immediately.","solutions":["Read the exception message/stderr buffer — it contains the CLI's final diagnostic lines explaining the exit","Verify the Copilot CLI is installed and runs manually (e.g. run the CLI binary directly to see its error)","Check CLI version compatibility with the SDK version and update one or both","Inspect the CLI config files and environment (auth, proxy, PATH) for invalid values"],"exampleFix":"// before\nvar client = new CopilotClient(options); // throws: Runtime process exited unexpectedly\n// after\ntry\n{\n    var client = new CopilotClient(options);\n}\ncatch (CopilotCliExitedException ex)\n{\n    Console.Error.WriteLine($\"CLI failed to start: {ex.Stderr}\"); // surface CLI diagnostics\n    throw;\n}","handlingStrategy":"try-catch","validationCode":"// C#: before constructing the client\nvar psi = new ProcessStartInfo(cliPath, \"--version\") { RedirectStandardError = true };\nusing var p = Process.Start(psi)!;\nif (p.WaitForExit(5000) && p.ExitCode != 0)\n    throw new InvalidOperationException($\"Copilot CLI unusable: {p.StandardError.ReadToEnd()}\");","typeGuard":null,"tryCatchPattern":"// C#\ntry { var client = new CopilotClient(options); }\ncatch (CopilotCliExitedException ex)\n{\n    logger.LogError(ex, \"CLI exited. Stderr: {Stderr}\", ex.Stderr);\n    throw;\n}","preventionTips":["Verify the CLI is installed, on PATH, and runs with --version before client startup","Keep SDK and CLI versions compatible","Log and inspect the stderr buffer included in the exception — it holds the root cause","Check CLI config files and proxy/auth environment for invalid values"],"tags":["dotnet","process-lifecycle","startup","cli"],"backgroundTag":"cli-process-exited","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"}