{"record":{"id":"993969160b1008ee","repo":"java-native-access/jna","slug":"unsatisfiedlinkerror-e-getmessage","errorCode":null,"errorMessage":"UnsatisfiedLinkError(e.getMessage())","messagePattern":"UnsatisfiedLinkError\\(e\\.getMessage\\(\\)\\)","errorType":"exception","errorClass":"java.lang.UnsatisfiedLinkError","httpStatus":null,"severity":"critical","filePath":"src/com/sun/jna/Native.java","lineNumber":1124,"sourceCode":"            }\n\n            LOG.log(DEBUG_JNA_LOAD_LEVEL, \"Trying {0}\", lib.getAbsolutePath());\n            System.setProperty(\"jnidispatch.path\", lib.getAbsolutePath());\n            System.load(lib.getAbsolutePath());\n            jnidispatchPath = lib.getAbsolutePath();\n            LOG.log(DEBUG_JNA_LOAD_LEVEL, \"Found jnidispatch at {0}\", jnidispatchPath);\n\n            // Attempt to delete immediately once jnidispatch is successfully\n            // loaded.  This avoids the complexity of trying to do so on \"exit\",\n            // which point can vary under different circumstances (native\n            // compilation, dynamically loaded modules, normal application, etc).\n            if (isUnpacked(lib)\n                && !Boolean.getBoolean(\"jnidispatch.preserve\")) {\n                deleteLibrary(lib);\n            }\n        }\n        catch(IOException e) {\n            throw new UnsatisfiedLinkError(e.getMessage());\n        }\n    }\n\n    /** Identify temporary files unpacked from classpath jar files. */\n    static boolean isUnpacked(File file) {\n        return file.getName().startsWith(JNA_TMPLIB_PREFIX);\n    }\n\n    /** Attempt to extract a native library from the current resource path,\n     * using the current thread context class loader.\n     * @param name Base name of native library to extract.  May also be an\n     * absolute resource path (i.e. starts with \"/\"), in which case the\n     * no transformations of the library name are performed.  If only the base\n     * name is given, the resource path is attempted both with and without\n     * {@link Platform#RESOURCE_PREFIX}, after mapping the library name via\n     * {@link NativeLibrary#mapSharedLibraryName(String)}.\n     * @return File indicating extracted resource on disk\n     * @throws IOException if resource not found","sourceCodeStart":1106,"sourceCodeEnd":1142,"githubUrl":"https://github.com/java-native-access/jna/blob/d036ad9781adad4b66693e8fa7098e4ac665e0a3/src/com/sun/jna/Native.java#L1106-L1142","documentation":"During loadNativeLibrary, after successfully System.load-ing the extracted jnidispatch library, JNA attempts cleanup (deleteLibrary) of the temporary file; an IOException raised inside this try block is rethrown as UnsatisfiedLinkError with the original IOException message. The native library load itself is wrapped here, so a genuine load failure with a textual reason also surfaces this way.","triggerScenarios":"System.load failing on the extracted library (wrong architecture, missing dependent shared objects, corrupt file) or an IOException during post-load temporary-file handling in loadNativeLibrary.","commonSituations":"Copying a 64-bit JRE onto a 32-bit libjnidispatch (or vice versa); running where required OS dependencies of jnidispatch are absent; read-only or full temp dirs causing I/O errors during unpack handling.","solutions":["Read the embedded message (e.getMessage()) for the true cause - typically 'wrong ELF class' or a missing dependent library","Match JVM bitness with the bundled native library (use a full official jna.jar for the platform)","Set -Djna.tmpdir to a writable directory with space, or -Djnidispatch.preserve=true to keep the extracted file for diagnosis","Run ldd/otool on the extracted libjnidispatch to find missing OS dependencies and install them"],"exampleFix":"// before\ncatch(IOException e) { /* silently lost */ }\n// after\ntry { /* ensure writable temp */ Files.createDirectories(Paths.get(System.getProperty(\"jna.tmpdir\", \"/var/tmp/app\"))); } catch (IOException e) { throw new RuntimeException(\"jna.tmpdir not writable: \" + e.getMessage(), e); }","handlingStrategy":"try-catch","validationCode":"// pre-checks before first JNA call\nString arch = System.getProperty(\"os.arch\");\nboolean jvm64 = System.getProperty(\"sun.arch.data.model\", \"64\").equals(\"64\");\nif (!jvm64 && arch.contains(\"64\")) throw new IllegalStateException(\"32-bit JVM with 64-bit natives likely - match bitness\");","typeGuard":null,"tryCatchPattern":"try { Native.load(\"c\", CLibrary.class); } catch (UnsatisfiedLinkError e) { String m = String.valueOf(e.getMessage()); if (m.contains(\"wrong ELF class\") || m.contains(\"Can't load library\") || m.contains(\"unable to load library\")) { throw new IllegalStateException(\"jnidispatch load failed: \" + m + \" - check bitness/OS deps\", e); } throw e; }","preventionTips":["Match JVM and native library bitness","Install OS dependencies jnidispatch requires (glibc, libffi on older systems)","Set a writable jna.tmpdir and consider -Djnidispatch.preserve=true when debugging"],"tags":["java","native-library","io","unsatisfied-link"],"backgroundTag":"file-read-failed","analyzedSha":"d036ad9781adad4b66693e8fa7098e4ac665e0a3","analyzedAt":"2026-09-12T06:50:59.239Z","contentChangedAt":"2026-09-12T06:50:59.239Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}