github/copilot-sdk · error · InvalidOperationException

Runtime process not started

Error message

Runtime process not started

What it means

When the connection mode is StdioRuntimeConnection, streams are wired to the spawned CLI process's stdin/stdout. This InvalidOperationException is thrown when the connection is stdio-mode but cliProcess was never spawned. It is an internal invariant: the client was started in stdio mode without a live process.

Solutions

1. Ensure the CLI process is spawned before stream wiring — check that the CLI path (cliPath) points to an existing executable.
2. Complete StartAsync and await it before using the client.
3. If a previous session crashed, create a fresh CopilotClient instead of reusing a disposed connection.
4. Report a bug with repro steps if spawn succeeds but cliProcess is still null — it indicates an SDK invariant violation.

Example fix

// before
var client = new CopilotClient();
await client.GetSessionAsync(...); // runtime not started

// after
var client = new CopilotClient();
await client.StartAsync(); // spawns CLI process first
await client.GetSessionAsync(...);

if (_connection is StdioRuntimeConnection && cliProcess is null)
    throw new InvalidOperationException("call StartAsync before using the client");

try { await session.SendAsync(msg); }
catch (InvalidOperationException ex) when (ex.Message == "Runtime process not started")
{ await client.StartAsync(); }

When it happens

Trigger: Calling StartAsync/stream wiring while _connection is StdioRuntimeConnection and the CLI process handle (cliProcess) is still null — e.g. process spawn failed silently or wiring ran before spawn.

Common situations: CLI executable path misconfigured so spawn never happened; calling client APIs before StartAsync completed; a previous process crash left the connection object alive with no process.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

• CLI process not started
• CLI child process was unexpectedly started in parent…
• An in-process FFI runtime library is already loaded from
• Exception of type 'System.ObjectDisposedException' was…
• Client is not started. Call StartAsync first.

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

Appendix: source

Thrown at dotnet/src/Client.cs:2642

    {
        var setupTimestamp = Stopwatch.GetTimestamp();
        NetworkStream? networkStream = null;
        JsonRpc? rpc = null;

        try
        {
            Stream inputStream, outputStream;

            if (ffiHost is not null)
            {
                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);

View on GitHub (pinned to cd8cf15dc3)