{"record":{"id":"a61f8a1019dbd2c8","repo":"github/copilot-sdk","slug":"failed-to-start-in-process-runtime-host","errorCode":null,"errorMessage":"Failed to start in-process runtime host.","messagePattern":"Failed to start in-process runtime host\\.","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"java/sdk/src/main/java/com/github/copilot/ffi/FfiRuntimeHost.java","lineNumber":259,"sourceCode":"    }\n\n    private int runHostStartOnBlockingThread(byte[] argvJson, byte[] envJson) {\n        ReaderThreadFactory readerThreadFactory = new ReaderThreadFactory();\n        ExecutorService executor = Executors\n                .newSingleThreadExecutor(runnable -> readerThreadFactory.create(runnable, \"copilot-ffi-host-start\"));\n        try {\n            Future<Integer> future = executor.submit(() -> nativeBinding.hostStart(argvJson, argvJson.length, envJson,\n                    envJson == null ? 0 : envJson.length));\n            return future.get();\n        } catch (InterruptedException e) {\n            Thread.currentThread().interrupt();\n            throw new IllegalStateException(\"Interrupted while starting in-process runtime host.\", e);\n        } catch (ExecutionException e) {\n            Throwable cause = e.getCause();\n            if (cause instanceof RuntimeException runtimeException) {\n                throw runtimeException;\n            }\n            throw new IllegalStateException(\"Failed to start in-process runtime host.\", cause);\n        } finally {\n            executor.shutdownNow();\n            try {\n                executor.awaitTermination(5, TimeUnit.SECONDS);\n            } catch (InterruptedException e) {\n                Thread.currentThread().interrupt();\n            }\n        }\n    }\n\n    private static byte[] buildArgvJson(String entrypointPath, CopilotClientOptions options) {\n        List<String> argv = new ArrayList<>();\n        if (entrypointPath != null) {\n            if (entrypointPath.toLowerCase().endsWith(\".js\")) {\n                argv.add(\"node\");\n            }\n            argv.add(entrypointPath);\n            argv.add(\"--embedded-host\");","sourceCodeStart":241,"sourceCodeEnd":277,"githubUrl":"https://github.com/github/copilot-sdk/blob/cd8cf15dc3f9e762615790aaed0a771a0f392755/java/sdk/src/main/java/com/github/copilot/ffi/FfiRuntimeHost.java#L241-L277","documentation":"The executor task running nativeBinding.hostStart threw a checked Throwable (not a RuntimeException). The library wraps the cause in IllegalStateException so callers get a consistent exception type from start().","triggerScenarios":"hostStart callable throws a checked exception or Error (e.g. LinkageError, OOM) not classified as RuntimeException; the original cause is attached via getCause().","commonSituations":"JVM-level failures during JNI/JNA invocation ( UnsatisfiedLinkError surfacing late, out-of-memory), or a bug in the binding layer throwing a checked exception.","solutions":["Inspect getCause() of the IllegalStateException for the real failure.","Fix the underlying cause (e.g. memory settings -Xmx, matching native lib).","If it's a LinkageError, ensure a single compatible JNA/native library on the classpath.","Retry after correcting environment; wrap start() to unwrap causes for logging."],"exampleFix":"// before\ncatch (IllegalStateException e) { log.error(e.getMessage()); }\n// after\ncatch (IllegalStateException e) { log.error(\"host start failed\", e.getCause()); }","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try { host.start(e, o); } catch (IllegalStateException ex) { Throwable root = ex; while (root.getCause() != null) root = root.getCause(); log.error(\"root cause\", root); }","preventionTips":["Always log the full cause chain, not just the message","Check JVM memory/linkage health when native calls fail","Keep JNA and native runtime versions aligned"],"tags":["java","ffi","wrapped-exception"],"backgroundTag":"module-init-failed","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"}