{"record":{"id":"a12134a3e9ee61d8","repo":"github/copilot-sdk","slug":"copilot-runtime-host-start-failed-library","errorCode":null,"errorMessage":"copilot_runtime_host_start failed (library '').","messagePattern":"copilot_runtime_host_start failed \\(library ''\\)\\.","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"critical","filePath":"java/sdk/src/main/java/com/github/copilot/ffi/FfiRuntimeHost.java","lineNumber":111,"sourceCode":"     * @param options\n     *            client options used to construct {@code argv_json} and\n     *            {@code env_json}\n     */\n    public void start(String entrypointPath, CopilotClientOptions options) {\n        Objects.requireNonNull(options, \"options must not be null\");\n        if (disposed.get()) {\n            throw new IllegalStateException(\"FfiRuntimeHost is already closed.\");\n        }\n        if (serverId.get() != 0 || connectionId.get() != 0) {\n            throw new IllegalStateException(\"FfiRuntimeHost has already been started.\");\n        }\n\n        byte[] argvJson = buildArgvJson(entrypointPath, options);\n        byte[] envJson = buildEnvJson(options);\n        int hostHandle = runHostStartOnBlockingThread(argvJson, envJson);\n        if (hostHandle == 0) {\n            String lib = libraryPath != null ? libraryPath : \"<unknown>\";\n            throw new IllegalStateException(\"copilot_runtime_host_start failed (library '\" + lib + \"').\");\n        }\n\n        // Hold operationLock while publishing handles to serialize with close().\n        // Recheck disposed in case close() ran while hostStart was blocking.\n        operationLock.lock();\n        try {\n            if (disposed.get()) {\n                try {\n                    nativeBinding.hostShutdown(hostHandle);\n                } catch (Throwable ignored) {\n                    // Best effort\n                }\n                throw new IllegalStateException(\"FfiRuntimeHost was closed during startup.\");\n            }\n            serverId.set(hostHandle);\n\n            OutboundCallback callback = createOutboundCallback();\n            callbackRef = callback;","sourceCodeStart":93,"sourceCodeEnd":129,"githubUrl":"https://github.com/github/copilot-sdk/blob/cd8cf15dc3f9e762615790aaed0a771a0f392755/java/sdk/src/main/java/com/github/copilot/ffi/FfiRuntimeHost.java#L93-L129","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Check the resolved libraryPath in the message and verify the native runtime exists and matches OS/arch.","Delete the cached runtime file so NativeRuntimeLoader re-extracts a fresh copy.","Enable FINE logging and run the native entrypoint directly to see the underlying native error.","Update the SDK/native runtime to matching versions."],"exampleFix":"// before\nhost.start(entrypoint, options); // fails with library '...'\n// after\nPath lib = NativeRuntimeLoader.ensureRuntime();\nif (!Files.exists(lib)) { throw new IOException(\"runtime missing: \" + lib); }\nhost.start(entrypoint, options);","handlingStrategy":"fallback","validationCode":"Path lib = NativeRuntimeLoader.ensureRuntime();\nif (!Files.exists(lib) || Files.size(lib) < MIN_RUNTIME_SIZE) throw new IOException(\"runtime missing/corrupt: \" + lib);","typeGuard":null,"tryCatchPattern":"try { host.start(e, o); } catch (IllegalStateException ex) { log.error(\"native start failed\", ex); /* purge cache and retry once */ }","preventionTips":["Verify native runtime checksum after download/extraction","Match runtime artifact to OS/arch and SDK version","Pre-warm and test host startup during deployment health checks"],"tags":["java","ffi","native","startup"],"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"}