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

Could not find JNA native support

Error message

Could not find JNA native support

What it means

After failing to load the native dispatch library from OS paths, JNA tries to extract /com/sun/jna/<RESOURCE_PREFIX>/libjnidispatch.* from the resource path. When extractFromResourcePath returns null - the resource is absent from the classpath - JNA throws this UnsatisfiedLinkError, meaning the JAR on the classpath lacks the native binaries for the current platform.

Source

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

    }

    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());
            if (lib == null) {
                throw new UnsatisfiedLinkError("Could not find JNA native support");
            }

            LOG.log(DEBUG_JNA_LOAD_LEVEL, "Trying {0}", lib.getAbsolutePath());
            System.setProperty("jnidispatch.path", lib.getAbsolutePath());
            System.load(lib.getAbsolutePath());
            jnidispatchPath = lib.getAbsolutePath();
            LOG.log(DEBUG_JNA_LOAD_LEVEL, "Found jnidispatch at {0}", jnidispatchPath);

            // Attempt to delete immediately once jnidispatch is successfully
            // loaded.  This avoids the complexity of trying to do so on "exit",
            // which point can vary under different circumstances (native
            // compilation, dynamically loaded modules, normal application, etc).
            if (isUnpacked(lib)
                && !Boolean.getBoolean("jnidispatch.preserve")) {
                deleteLibrary(lib);
            }
        }
        catch(IOException e) {

View on GitHub (pinned to d036ad9781)

Solutions

  1. Replace the classpath JAR with the official full jna.jar matching (or exceeding) your JNA version so it includes natives for your platform prefix
  2. Verify the resource exists: the JAR must contain com/sun/jna/<Platform.RESOURCE_PREFIX>/libjnidispatch.*
  3. Pre-install the native library and set -Djna.boot.library.path to its directory as a fallback
  4. Log Platform.RESOURCE_PREFIX and the classpath to confirm the expected prefix and JAR are actually used by the effective classloader

Example fix

// before (minimized jar missing natives)
<artifactItem><artifactId>jna</artifactId><excludes>com/sun/jna/**</excludes></artifactItem>
// after
<dependency><groupId>net.java.dev.jna</groupId><artifactId>jna</artifactId><version>5.x</version></dependency>
Defensive patterns

Strategy: fallback

Validate before calling

// verify the native resource exists before first JNA call
String prefix = com.sun.jna.Platform.RESOURCE_PREFIX;
String res = "/com/sun/jna/" + prefix + "/" + (com.sun.jna.Platform.isWindows() ? "jnidispatch.dll" : "libjnidispatch.so");
if (Native.class.getResourceAsStream(res) == null) {
    throw new IllegalStateException("jnidispatch resource missing for prefix " + prefix + " - replace jna.jar");
}

Try / catch

try { Native.load("c", CLibrary.class); } catch (UnsatisfiedLinkError e) { if (String.valueOf(e.getMessage()).contains("Could not find JNA native support")) { throw new IllegalStateException("Classpath jna.jar lacks natives for " + com.sun.jna.Platform.RESOURCE_PREFIX, e); } throw e; }

Prevention

When it happens

Trigger: Loading any JNA-based library when the classpath contains a jna.jar without native resources for Platform.RESOURCE_PREFIX (e.g. linux-x86-64), or a repackaged/minimized JAR stripped of .so/.dll/.dylib files.

Common situations: Using a 'slim' or shaded JAR that dropped native resources; mixing an old jna.jar with a newer jnidispatch; running an uncommon platform (e.g. linux-aarch64) with a JAR built without that prefix; application-server classloader not exposing the resource.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

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