java-native-access/jna · error · java.io.IOException

Native library (resourcePath) not found in resource path (pa

Error message

Native library (resourcePath) not found in resource path (path)

What it means

extractFromResourcePath could not resolve the given native-library resource path via the supplied ClassLoader or any classpath URL, so it throws IOException 'Native library (resourcePath) not found in resource path (path)', echoing the resource being sought and the effective classpath/URLs searched. Callers like loadNativeLibrary convert this into UnsatisfiedLinkError.

Source

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

                // Fallback for legacy darwin behaviour: darwin was in the past
                // special cased in that all architectures were mapped to the same
                // prefix and it was expected, that a fat binary was present at that
                // point, that contained all architectures.
                if(Platform.RESOURCE_PREFIX.startsWith("com/sun/jna/darwin")) {
                    url = loader.getResource("com/sun/jna/darwin" + resourcePath.substring(("com/sun/jna/" + Platform.RESOURCE_PREFIX).length() + 1));
                }
                if (url == null) {
                    // If not found with the standard resource prefix, try without it
                    url = loader.getResource(libname);
                }
            }
        }
        if (url == null) {
            String path = System.getProperty("java.class.path");
            if (loader instanceof URLClassLoader) {
                path = Arrays.asList(((URLClassLoader)loader).getURLs()).toString();
            }
            throw new IOException("Native library (" + resourcePath + ") not found in resource path (" + path + ")");
        }
        LOG.log(DEBUG, "Found library resource at {0}", url);

        File lib = null;
        if (url.getProtocol().toLowerCase().equals("file")) {
            try {
                lib = new File(new URI(url.toString()));
            }
            catch(URISyntaxException e) {
                lib = new File(url.getPath());
            }
            LOG.log(DEBUG, "Looking in {0}", lib.getAbsolutePath());
            if (!lib.exists()) {
                throw new IOException("File URL " + url + " could not be properly decoded");
            }
        }
        else if (!Boolean.getBoolean("jna.nounpack")) {
            InputStream is = url.openStream();

View on GitHub (pinned to d036ad9781)

Solutions

  1. Ensure the JAR containing the resource (com/sun/jna/<prefix>/<lib>) is on the effective classpath of the loader being used
  2. Inspect the printed resource path list in the message and add the missing classpath entry or JAR
  3. Pass the correct ClassLoader argument to extractFromResourcePath instead of one that cannot see the resource
  4. Pre-extract the library to the filesystem and load it by absolute path instead of from the resource path

Example fix

// before
Native.extractFromResourcePath("/com/sun/jna/linux-x86/libjnidispatch.so", limitedLoader);
// after
Native.extractFromResourcePath("/com/sun/jna/" + Platform.RESOURCE_PREFIX + "/libjnidispatch." + Platform.getNativeLibraryResourceSuffix(), Native.class.getClassLoader());
Defensive patterns

Strategy: validation

Validate before calling

// ensure the resource is visible to the classloader you will use
String res = "/com/sun/jna/" + com.sun.jna.Platform.RESOURCE_PREFIX + "/libjnidispatch.so";
if (loader.getResource(res) == null) {
    throw new IllegalStateException(res + " not visible to loader " + loader);
}

Try / catch

try { Native.extractFromResourcePath(res, loader); } catch (IOException e) { if (String.valueOf(e.getMessage()).startsWith("Native library (") && e.getMessage().contains("not found in resource path")) { throw new IllegalStateException("Add the JAR containing " + res + " to the classpath", e); } throw e; }

Prevention

When it happens

Trigger: extractFromResourcePath invoked (directly or via JNA library loading) with a resourcePath that no ClassLoader on the search path can resolve - e.g. the platform-native folder is missing from all classpath entries.

Common situations: fat-jar assembly excluding native resources; custom URLClassLoader whose URLs omit the JAR holding the natives; typo'd or stale resource prefix; running on a platform whose prefix directory was never packaged.

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/b4ffa13ffc78d145. Report an issue: GitHub.