{"record":{"id":"abc3069605ca9cc0","repo":"github/copilot-sdk","slug":"failed-to-load-native-library-from","errorCode":null,"errorMessage":"Failed to load native library from ''","messagePattern":"Failed to load native library from ''","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"critical","filePath":"java/sdk/src/main/java/com/github/copilot/ffi/JnaNativeBinding.java","lineNumber":202,"sourceCode":"\n    /**\n     * Loads (or re-uses) the native library at the given absolute path.\n     *\n     * @param libraryPath\n     *            absolute path to the {@code runtime.node} native library\n     * @throws IllegalStateException\n     *             if a <em>different</em> library path has already been loaded in\n     *             this JVM process\n     */\n    JnaNativeBinding(Path libraryPath) {\n        Path absPath = libraryPath.toAbsolutePath().normalize();\n        synchronized (LOAD_LOCK) {\n            if (loadedLib == null) {\n                LOG.fine(() -> \"Loading native library from: \" + absPath);\n                try {\n                    loadedLib = Native.load(absPath.toString(), CopilotRuntimeLibrary.class);\n                } catch (UnsatisfiedLinkError e) {\n                    throw new IllegalStateException(\"Failed to load native library from '\" + absPath + \"'\", e);\n                }\n                loadedPath = absPath;\n                LOG.fine(() -> \"Native library loaded: \" + absPath);\n            } else if (!absPath.equals(loadedPath)) {\n                throw new IllegalStateException(\"An in-process FFI runtime library is already loaded from '\"\n                        + loadedPath + \"'; loading a different library from '\" + absPath\n                        + \"' in the same process is not supported.\");\n            }\n        }\n        this.lib = loadedLib;\n    }\n\n    /**\n     * Testing constructor — accepts a pre-built {@link CopilotRuntimeLibrary}\n     * directly, bypassing disk I/O and the static singleton guard.\n     *\n     * <p>\n     * This constructor is package-private and intended solely for unit tests.","sourceCodeStart":184,"sourceCodeEnd":220,"githubUrl":"https://github.com/github/copilot-sdk/blob/cd8cf15dc3f9e762615790aaed0a771a0f392755/java/sdk/src/main/java/com/github/copilot/ffi/JnaNativeBinding.java#L184-L220","documentation":"JnaNativeBinding's constructor loads the native runtime via Native.load(); an UnsatisfiedLinkError (missing symbols, wrong architecture, corrupt or dependency-lacking library) is converted to IllegalStateException including the absolute path attempted.","triggerScenarios":"Native.load(absPath) fails: the extracted runtime file is corrupt/truncated, built for a different OS/arch, or missing transitive native dependencies (e.g. missing libc++/openssl).","commonSituations":"Downloading/extracting the runtime over a bad network leaving a truncated file; copying a linux-x64 binary to an arm64 machine; missing system libraries in a slim Docker image.","solutions":["Delete the cached runtime file so it is re-extracted from a pristine source.","Verify the binary architecture matches the JVM (file/libext on the .so/.dylib).","Run ldd/otool on the library to find missing native dependencies and install them.","Confirm the JDK bitness/OS matches the runtime artifact; update the loader/SDK."],"exampleFix":"// before\nFiles.move(downloaded, cachePath); // may be truncated\n// after\nif (checksum(downloaded) != expectedChecksum) throw new IOException(\"corrupt runtime\");\nFiles.move(downloaded, cachePath, StandardCopyOption.ATOMIC_MOVE);","handlingStrategy":"fallback","validationCode":"if (!Files.isReadable(libPath)) throw new IOException(\"native lib unreadable\");\nProcess p = new ProcessBuilder(\"file\", libPath.toString()).inheritIO().start(); p.waitFor();","typeGuard":null,"tryCatchPattern":"try { binding = new JnaNativeBinding(libPath); } catch (IllegalStateException ex) { purgeCache(); binding = new JnaNativeBinding(reextract(libPath)); }","preventionTips":["Validate runtime checksum/size after extraction","Verify OS/arch of the artifact before shipping","Install required native dependencies in the (Docker) image","Run ldd/otool in CI to catch missing libs early"],"tags":["java","jna","native","library-loading"],"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"}