github/copilot-sdk · critical · CompletionException

CLI process exited unexpectedly.

Error message

CLI process exited unexpectedly.

What it means

During client startup, if the CLI process terminates before handshake completes, the SDK wraps the failure in a CompletionException. If the server manager captured stderr output, it rethrows an IOException whose message is 'CLI process exited unexpectedly.' followed by the CLI's stderr, so the developer can see why the process died.

Solutions

1. Read the stderr appended to the message — it contains the CLI's own error
2. Verify the CLI path/URL and that the binary is installed and executable
3. Update the CLI to a compatible version and retry

Example fix

// catch pattern
try { client.start().join(); }
catch (CompletionException e) {
    Throwable c = e.getCause();
    if (c instanceof IOException && c.getMessage().startsWith("CLI process exited unexpectedly.")) {
        // inspect c.getMessage() for stderr details
    }
}

// preflight: verify the CLI binary exists and is executable
Process p = new ProcessBuilder(cliPath, "--version").start();
if (p.waitFor(10, TimeUnit.SECONDS) && p.exitValue() != 0) throw new IllegalStateException("CLI unusable");

try { client.start().join(); } catch (CompletionException e) { if (e.getCause() instanceof IOException io && io.getMessage().startsWith("CLI process exited unexpectedly.")) { log(io.getMessage()); } else throw e; }

When it happens

Trigger: startCoreBody spawns the CLI and it exits early: bad executable path, missing dependencies, crash on startup, port/permission problems — any non-empty stderr captured at startup.

Common situations: Wrong CLI path or outdated/missing GitHub Copilot CLI binary; the CLI failing to authenticate or crashing on launch; sandboxed environments blocking process spawn.

Related errors

• Timeout waiting for CLI to announce port
• Cannot connect: no process for stdio and no host:port for…
• CLI process exited unexpectedly.
• copilot_runtime_host_start failed (library '').
• Runtime process exited unexpectedly

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

Appendix: source

Thrown at java/sdk/src/main/java/com/github/copilot/CopilotClient.java:622

                        startNanos);
            }
            // Clean up the spawned process if connection setup failed
            if (process != null) {
                cleanupCliProcess(process, true);
            }
            if (rpc != null) {
                try {
                    rpc.close();
                } catch (Exception closeError) {
                    LOG.log(Level.FINE, "Error closing RPC after failed startup", closeError);
                }
            }
            if (inProcessTransport != null) {
                closeRuntimeHost(inProcessTransport.host());
            }
            String stderr = serverManager.getStderrOutput();
            if (!stderr.isEmpty()) {
                throw new CompletionException(new IOException(
                        CliServerManager.formatCliExitedMessage("CLI process exited unexpectedly.", stderr), e));
            }
            throw new CompletionException(e);
        }
    }

    private static final int MIN_PROTOCOL_VERSION = 2;
    private static final int METHOD_NOT_FOUND_ERROR_CODE = -32601;

    private void verifyProtocolVersion(Connection connection) throws Exception {
        int expectedVersion = SdkProtocolVersion.get();
        Integer serverVersion;

        try {
            // Try the new 'connect' RPC which supports connection tokens.
            var connectParams = new HashMap<String, Object>();
            if (effectiveConnectionToken != null) {
                connectParams.put("token", effectiveConnectionToken);

View on GitHub (pinned to cd8cf15dc3)