github/copilot-sdk · critical · IOException

Runtime process exited unexpectedly

Error message

Runtime process exited unexpectedly

What it means

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.

Solutions

1. Read the exception message/stderr buffer — it contains the CLI's final diagnostic lines explaining the exit
2. Verify the Copilot CLI is installed and runs manually (e.g. run the CLI binary directly to see its error)
3. Check CLI version compatibility with the SDK version and update one or both
4. Inspect the CLI config files and environment (auth, proxy, PATH) for invalid values

Example fix

// before
var client = new CopilotClient(options); // throws: Runtime process exited unexpectedly
// after
try
{
    var client = new CopilotClient(options);
}
catch (CopilotCliExitedException ex)
{
    Console.Error.WriteLine($"CLI failed to start: {ex.Stderr}"); // surface CLI diagnostics
    throw;
}

// C#: before constructing the client
var psi = new ProcessStartInfo(cliPath, "--version") { RedirectStandardError = true };
using var p = Process.Start(psi)!;
if (p.WaitForExit(5000) && p.ExitCode != 0)
    throw new InvalidOperationException($"Copilot CLI unusable: {p.StandardError.ReadToEnd()}");

// C#
try { var client = new CopilotClient(options); }
catch (CopilotCliExitedException ex)
{
    logger.LogError(ex, "CLI exited. Stderr: {Stderr}", ex.Stderr);
    throw;
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Timeout waiting for CLI to announce port
• CLI process exited unexpectedly.
• Invalid value ' '. Expected 'inprocess', 'stdio', or unset.
• In-process FFI runtime library not found at
• CLI process exited unexpectedly. stderr

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

Appendix: source

Thrown at dotnet/src/Client.cs:2445

                        {
                            detectedLocalhostTcpPort = int.Parse(match.Groups[1].Value, CultureInfo.InvariantCulture);
                            LoggingHelpers.LogTiming(logger, LogLevel.Debug, null,
                                "CopilotClient.StartCliServerAsync TCP port wait complete. Elapsed={Elapsed}, Port={Port}",
                                portWaitTimestamp,
                                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;
        }
    }

View on GitHub (pinned to cd8cf15dc3)