{"record":{"id":"74855b39fd35ee7d","repo":"github/copilot-sdk","slug":"cli-process-exited-unexpectedly-74855b","errorCode":null,"errorMessage":"CLI process exited unexpectedly.","messagePattern":"CLI process exited unexpectedly\\.","errorType":"exception","errorClass":"CompletionException","httpStatus":null,"severity":"critical","filePath":"java/sdk/src/main/java/com/github/copilot/CopilotClient.java","lineNumber":622,"sourceCode":"                        startNanos);\n            }\n            // Clean up the spawned process if connection setup failed\n            if (process != null) {\n                cleanupCliProcess(process, true);\n            }\n            if (rpc != null) {\n                try {\n                    rpc.close();\n                } catch (Exception closeError) {\n                    LOG.log(Level.FINE, \"Error closing RPC after failed startup\", closeError);\n                }\n            }\n            if (inProcessTransport != null) {\n                closeRuntimeHost(inProcessTransport.host());\n            }\n            String stderr = serverManager.getStderrOutput();\n            if (!stderr.isEmpty()) {\n                throw new CompletionException(new IOException(\n                        CliServerManager.formatCliExitedMessage(\"CLI process exited unexpectedly.\", stderr), e));\n            }\n            throw new CompletionException(e);\n        }\n    }\n\n    private static final int MIN_PROTOCOL_VERSION = 2;\n    private static final int METHOD_NOT_FOUND_ERROR_CODE = -32601;\n\n    private void verifyProtocolVersion(Connection connection) throws Exception {\n        int expectedVersion = SdkProtocolVersion.get();\n        Integer serverVersion;\n\n        try {\n            // Try the new 'connect' RPC which supports connection tokens.\n            var connectParams = new HashMap<String, Object>();\n            if (effectiveConnectionToken != null) {\n                connectParams.put(\"token\", effectiveConnectionToken);","sourceCodeStart":604,"sourceCodeEnd":640,"githubUrl":"https://github.com/github/copilot-sdk/blob/cd8cf15dc3f9e762615790aaed0a771a0f392755/java/sdk/src/main/java/com/github/copilot/CopilotClient.java#L604-L640","documentation":"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.","triggerScenarios":"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.","commonSituations":"Wrong CLI path or outdated/missing GitHub Copilot CLI binary; the CLI failing to authenticate or crashing on launch; sandboxed environments blocking process spawn.","solutions":["Read the stderr appended to the message — it contains the CLI's own error","Verify the CLI path/URL and that the binary is installed and executable","Update the CLI to a compatible version and retry"],"exampleFix":"// catch pattern\ntry { client.start().join(); }\ncatch (CompletionException e) {\n    Throwable c = e.getCause();\n    if (c instanceof IOException && c.getMessage().startsWith(\"CLI process exited unexpectedly.\")) {\n        // inspect c.getMessage() for stderr details\n    }\n}","handlingStrategy":"try-catch","validationCode":"// preflight: verify the CLI binary exists and is executable\nProcess p = new ProcessBuilder(cliPath, \"--version\").start();\nif (p.waitFor(10, TimeUnit.SECONDS) && p.exitValue() != 0) throw new IllegalStateException(\"CLI unusable\");","typeGuard":null,"tryCatchPattern":"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; }","preventionTips":["Log and inspect the stderr included in the message","Verify CLI installation/path before start","Keep the CLI version compatible with the SDK","Catch CompletionException and unwrap getCause()"],"tags":["java","cli","process-crash","startup"],"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"}