{"record":{"id":"c48afbcf6a63ae97","repo":"java-native-access/jna","slug":"unable-to-locate-jna-native-support-library","errorCode":null,"errorMessage":"Unable to locate JNA native support library","messagePattern":"Unable to locate JNA native support library","errorType":"exception","errorClass":"java.lang.UnsatisfiedLinkError","httpStatus":null,"severity":"critical","filePath":"src/com/sun/jna/Native.java","lineNumber":1085,"sourceCode":"                }\n            }\n        }\n        String jnaNosys = System.getProperty(\"jna.nosys\", \"true\");\n        if ((!Boolean.parseBoolean(jnaNosys)) || Platform.isAndroid()) {\n            try {\n                LOG.log(DEBUG_JNA_LOAD_LEVEL, \"Trying (via loadLibrary) {0}\", libName);\n                System.loadLibrary(libName);\n                LOG.log(DEBUG_JNA_LOAD_LEVEL, \"Found jnidispatch on system path\");\n                return;\n            }\n            catch(UnsatisfiedLinkError e) {\n            }\n        }\n        if (!Boolean.getBoolean(\"jna.noclasspath\")) {\n            loadNativeDispatchLibraryFromClasspath();\n        }\n        else {\n            throw new UnsatisfiedLinkError(\"Unable to locate JNA native support library\");\n        }\n    }\n\n    static final String JNA_TMPLIB_PREFIX = \"jna\";\n    /**\n     * Attempts to load the native library resource from the filesystem,\n     * extracting the JNA stub library from jna.jar if not already available.\n     */\n    private static void loadNativeDispatchLibraryFromClasspath() {\n        try {\n            String mappedName = System.mapLibraryName(\"jnidispatch\").replace(\".dylib\", \".jnilib\");\n            if(Platform.isAIX()) {\n                // OpenJDK is reported to map to .so -- this works around the\n                // difference between J9 and OpenJDK\n                mappedName = \"libjnidispatch.a\";\n            }\n            String libName = \"/com/sun/jna/\" + Platform.RESOURCE_PREFIX + \"/\" + mappedName;\n            File lib = extractFromResourcePath(libName, Native.class.getClassLoader());","sourceCodeStart":1067,"sourceCodeEnd":1103,"githubUrl":"https://github.com/java-native-access/jna/blob/d036ad9781adad4b66693e8fa7098e4ac665e0a3/src/com/sun/jna/Native.java#L1067-L1103","documentation":"JNA could not locate its bundled native support library (libjnidispatch.so/jnidispatch.dll/libjnidispatch.dylib) and the system property jna.noclasspath=true prevented it from trying to load it from the classpath, so it throws UnsatisfiedLinkError. JNA cannot perform any native calls without this embedded library.","triggerScenarios":"Starting the JVM with -Djna.noclasspath=true while the native dispatch library is not already loadable via jna.boot.library.path, java.library.path, or jnidispatch.path.","commonSituations":"Hardened/container deployments that set jna.noclasspath to force OS-level loading but forgot to install libjnidispatch; incomplete classpath JAR that excludes the native binaries; cross-platform repackaged JARs stripped of resources.","solutions":["Remove -Djna.noclasspath or set it to false so JNA loads the bundled library from the classpath","Install the native library and point -Djna.boot.library.path (or java.library.path) at its directory","Set the jnidispatch.path system property to the full path of the native library file","Use the complete, unmodified jna.jar for your platform (or jna-platform with natives intact)"],"exampleFix":"// before\njava -Djna.noclasspath=true -jar app.jar\n// after\njava -Djna.boot.library.path=/usr/local/lib -jar app.jar","handlingStrategy":"fallback","validationCode":"// startup self-check\nString bootPath = System.getProperty(\"jna.boot.library.path\", \"\");\nboolean noclasspath = Boolean.getBoolean(\"jna.noclasspath\");\nif (noclasspath && bootPath.isEmpty()) {\n    throw new IllegalStateException(\"jna.noclasspath=true but no jna.boot.library.path/jnidispatch.path provided\");\n}","typeGuard":null,"tryCatchPattern":"try { Native.load(\"c\", CLibrary.class); } catch (UnsatisfiedLinkError e) { if (String.valueOf(e.getMessage()).contains(\"Unable to locate JNA native support library\")) { System.setProperty(\"jna.noclasspath\", \"false\"); /* re-init */ } else throw e; }","preventionTips":["Do not set jna.noclasspath unless you also provide jna.boot.library.path or jnidispatch.path","Ship the official full jna.jar with native resources included","Add a smoke test that loads a trivial JNA library at startup"],"tags":["java","native-library","unsatisfied-link","classpath"],"backgroundTag":"missing-dependency","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"}