java-native-access/jna · critical · java.lang.UnsatisfiedLinkError

Unable to locate JNA native support library

Error message

Unable to locate JNA native support library

What it means

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.

Source

Thrown at src/com/sun/jna/Native.java:1085

                }
            }
        }
        String jnaNosys = System.getProperty("jna.nosys", "true");
        if ((!Boolean.parseBoolean(jnaNosys)) || Platform.isAndroid()) {
            try {
                LOG.log(DEBUG_JNA_LOAD_LEVEL, "Trying (via loadLibrary) {0}", libName);
                System.loadLibrary(libName);
                LOG.log(DEBUG_JNA_LOAD_LEVEL, "Found jnidispatch on system path");
                return;
            }
            catch(UnsatisfiedLinkError e) {
            }
        }
        if (!Boolean.getBoolean("jna.noclasspath")) {
            loadNativeDispatchLibraryFromClasspath();
        }
        else {
            throw new UnsatisfiedLinkError("Unable to locate JNA native support library");
        }
    }

    static final String JNA_TMPLIB_PREFIX = "jna";
    /**
     * Attempts to load the native library resource from the filesystem,
     * extracting the JNA stub library from jna.jar if not already available.
     */
    private static void loadNativeDispatchLibraryFromClasspath() {
        try {
            String mappedName = System.mapLibraryName("jnidispatch").replace(".dylib", ".jnilib");
            if(Platform.isAIX()) {
                // OpenJDK is reported to map to .so -- this works around the
                // difference between J9 and OpenJDK
                mappedName = "libjnidispatch.a";
            }
            String libName = "/com/sun/jna/" + Platform.RESOURCE_PREFIX + "/" + mappedName;
            File lib = extractFromResourcePath(libName, Native.class.getClassLoader());

View on GitHub (pinned to d036ad9781)

Solutions

1. Remove -Djna.noclasspath or set it to false so JNA loads the bundled library from the classpath
2. Install the native library and point -Djna.boot.library.path (or java.library.path) at its directory
3. Set the jnidispatch.path system property to the full path of the native library file
4. Use the complete, unmodified jna.jar for your platform (or jna-platform with natives intact)

Example fix

// before
java -Djna.noclasspath=true -jar app.jar
// after
java -Djna.boot.library.path=/usr/local/lib -jar app.jar

// startup self-check
String bootPath = System.getProperty("jna.boot.library.path", "");
boolean noclasspath = Boolean.getBoolean("jna.noclasspath");
if (noclasspath && bootPath.isEmpty()) {
    throw new IllegalStateException("jna.noclasspath=true but no jna.boot.library.path/jnidispatch.path provided");
}

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; }

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "not installed", "pip install", "required for": how missing-dependency errors surface across open-source libraries — this error's family across 34 libraries.

Related errors

• Could not find JNA native support
• UnsatisfiedLinkError(e.getMessage())
• There is an incompatible JNA native library installed on thi
• Native library (resourcePath) not found in resource path (pa
• Can't obtain InputStream for resourcePath

AI-assisted analysis of java-native-access/jna@d036ad9781 (2026-09-12). Data as JSON: /api/errors/c48afbcf6a63ae97. Report an issue: GitHub.