github/copilot-sdk · critical · IllegalStateException

copilot_runtime_host_start failed (library '').

Error message

copilot_runtime_host_start failed (library '').

What it means

The native function copilot_runtime_host_start returned a zero handle, meaning it failed to start the in-process runtime host. The library surfaces the native library path in the message to help diagnose load/config problems.

Solutions

1. Check the resolved libraryPath in the message and verify the native runtime exists and matches OS/arch.
2. Delete the cached runtime file so NativeRuntimeLoader re-extracts a fresh copy.
3. Enable FINE logging and run the native entrypoint directly to see the underlying native error.
4. Update the SDK/native runtime to matching versions.

Example fix

// before
host.start(entrypoint, options); // fails with library '...'
// after
Path lib = NativeRuntimeLoader.ensureRuntime();
if (!Files.exists(lib)) { throw new IOException("runtime missing: " + lib); }
host.start(entrypoint, options);

Path lib = NativeRuntimeLoader.ensureRuntime();
if (!Files.exists(lib) || Files.size(lib) < MIN_RUNTIME_SIZE) throw new IOException("runtime missing/corrupt: " + lib);

try { host.start(e, o); } catch (IllegalStateException ex) { log.error("native start failed", ex); /* purge cache and retry once */ }

When it happens

Trigger: hostStart native call returns 0: corrupted or mismatched native runtime library, invalid argv/env JSON rejected natively, unsupported platform binary, or native-side initialization failure (missing deps, resource limits).

Common situations: Deploying on an OS/arch without the matching .so/.dll/.dylib, a stale cached runtime extracted by NativeRuntimeLoader, or a native library built against an incompatible protocol version.

Related errors

• copilot_runtime_connection_open failed.
• copilot_runtime_host_start failed
• copilot_runtime_host_start failed
• copilot_runtime_connection_open failed.
• Timeout waiting for CLI to announce port

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

Appendix: source

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

     * @param options
     *            client options used to construct {@code argv_json} and
     *            {@code env_json}
     */
    public void start(String entrypointPath, CopilotClientOptions options) {
        Objects.requireNonNull(options, "options must not be null");
        if (disposed.get()) {
            throw new IllegalStateException("FfiRuntimeHost is already closed.");
        }
        if (serverId.get() != 0 || connectionId.get() != 0) {
            throw new IllegalStateException("FfiRuntimeHost has already been started.");
        }

        byte[] argvJson = buildArgvJson(entrypointPath, options);
        byte[] envJson = buildEnvJson(options);
        int hostHandle = runHostStartOnBlockingThread(argvJson, envJson);
        if (hostHandle == 0) {
            String lib = libraryPath != null ? libraryPath : "<unknown>";
            throw new IllegalStateException("copilot_runtime_host_start failed (library '" + lib + "').");
        }

        // Hold operationLock while publishing handles to serialize with close().
        // Recheck disposed in case close() ran while hostStart was blocking.
        operationLock.lock();
        try {
            if (disposed.get()) {
                try {
                    nativeBinding.hostShutdown(hostHandle);
                } catch (Throwable ignored) {
                    // Best effort
                }
                throw new IllegalStateException("FfiRuntimeHost was closed during startup.");
            }
            serverId.set(hostHandle);

            OutboundCallback callback = createOutboundCallback();
            callbackRef = callback;

View on GitHub (pinned to cd8cf15dc3)