github/copilot-sdk · error · IllegalStateException

Failed to start in-process runtime host.

Error message

Failed to start in-process runtime host.

What it means

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().

Solutions

1. Inspect getCause() of the IllegalStateException for the real failure.
2. Fix the underlying cause (e.g. memory settings -Xmx, matching native lib).
3. If it's a LinkageError, ensure a single compatible JNA/native library on the classpath.
4. Retry after correcting environment; wrap start() to unwrap causes for logging.

Example fix

// before
catch (IllegalStateException e) { log.error(e.getMessage()); }
// after
catch (IllegalStateException e) { log.error("host start failed", e.getCause()); }

try { host.start(e, o); } catch (IllegalStateException ex) { Throwable root = ex; while (root.getCause() != null) root = root.getCause(); log.error("root cause", root); }

When it happens

Trigger: hostStart callable throws a checked exception or Error (e.g. LinkageError, OOM) not classified as RuntimeException; the original cause is attached via getCause().

Common situations: JVM-level failures during JNI/JNA invocation ( UnsatisfiedLinkError surfacing late, out-of-memory), or a bug in the binding layer throwing a checked exception.

Related errors

• FfiRuntimeHost has already been started.
• copilot_runtime_host_start failed (library '').
• FfiRuntimeHost was closed during startup.
• copilot_runtime_connection_open failed.
• Interrupted while starting in-process runtime host.

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

Appendix: source

Thrown at java/sdk/src/main/java/com/github/copilot/ffi/FfiRuntimeHost.java:259

    }

    private int runHostStartOnBlockingThread(byte[] argvJson, byte[] envJson) {
        ReaderThreadFactory readerThreadFactory = new ReaderThreadFactory();
        ExecutorService executor = Executors
                .newSingleThreadExecutor(runnable -> readerThreadFactory.create(runnable, "copilot-ffi-host-start"));
        try {
            Future<Integer> future = executor.submit(() -> nativeBinding.hostStart(argvJson, argvJson.length, envJson,
                    envJson == null ? 0 : envJson.length));
            return future.get();
        } catch (InterruptedException e) {
            Thread.currentThread().interrupt();
            throw new IllegalStateException("Interrupted while starting in-process runtime host.", e);
        } catch (ExecutionException e) {
            Throwable cause = e.getCause();
            if (cause instanceof RuntimeException runtimeException) {
                throw runtimeException;
            }
            throw new IllegalStateException("Failed to start in-process runtime host.", cause);
        } finally {
            executor.shutdownNow();
            try {
                executor.awaitTermination(5, TimeUnit.SECONDS);
            } catch (InterruptedException e) {
                Thread.currentThread().interrupt();
            }
        }
    }

    private static byte[] buildArgvJson(String entrypointPath, CopilotClientOptions options) {
        List<String> argv = new ArrayList<>();
        if (entrypointPath != null) {
            if (entrypointPath.toLowerCase().endsWith(".js")) {
                argv.add("node");
            }
            argv.add(entrypointPath);
            argv.add("--embedded-host");

View on GitHub (pinned to cd8cf15dc3)