{"record":{"id":"19b8b4334262353c","repo":"java-native-access/jna","slug":"failed-to-load-library-libraryname","errorCode":null,"errorMessage":"Failed to load library 'libraryName'","messagePattern":"Failed to load library 'libraryName'","errorType":"exception","errorClass":"java.lang.UnsatisfiedLinkError","httpStatus":null,"severity":"critical","filePath":"src/com/sun/jna/NativeLibrary.java","lineNumber":228,"sourceCode":"        //\n        try {\n            LOG.log(DEBUG_LOAD_LEVEL, \"Trying \" + libraryPath);\n            handle = Native.open(libraryPath, openFlags);\n        } catch(UnsatisfiedLinkError e) {\n            // Add the system paths back for all fallback searching\n            LOG.log(DEBUG_LOAD_LEVEL, \"Loading failed with message: \" + e.getMessage());\n            LOG.log(DEBUG_LOAD_LEVEL, \"Adding system paths: \" + librarySearchPath);\n            exceptions.add(e);\n            searchPath.addAll(librarySearchPath);\n        }\n\n        try {\n            if (handle == 0) {\n                libraryPath = findLibraryPath(libraryName, searchPath);\n                LOG.log(DEBUG_LOAD_LEVEL, \"Trying \" + libraryPath);\n                handle = Native.open(libraryPath, openFlags);\n                if (handle == 0) {\n                    throw new UnsatisfiedLinkError(\"Failed to load library '\" + libraryName + \"'\");\n                }\n            }\n        } catch(UnsatisfiedLinkError ule) {\n            LOG.log(DEBUG_LOAD_LEVEL, \"Loading failed with message: \" + ule.getMessage());\n            exceptions.add(ule);\n            // For android, try to \"preload\" the library using\n            // System.loadLibrary(), which looks into the private /data/data\n            // path, not found in any properties\n            if (Platform.isAndroid()) {\n                try {\n                    LOG.log(DEBUG_LOAD_LEVEL, \"Preload (via System.loadLibrary) \" + libraryName);\n                    System.loadLibrary(libraryName);\n                    handle = Native.open(libraryPath, openFlags);\n                }\n                catch(UnsatisfiedLinkError e2) {\n                    LOG.log(DEBUG_LOAD_LEVEL, \"Loading failed with message: \" + e2.getMessage());\n                    exceptions.add(e2);\n                }","sourceCodeStart":210,"sourceCodeEnd":246,"githubUrl":"https://github.com/java-native-access/jna/blob/d036ad9781adad4b66693e8fa7098e4ac665e0a3/src/com/sun/jna/NativeLibrary.java#L210-L246","documentation":"NativeLibrary.getInstance throws UnsatisfiedLinkError when Native.open cannot load the shared library at the resolved path. The error is collected into a list of attempts because JNA may retry alternate search strategies (e.g. Android preloading) before giving up.","triggerScenarios":"Calling NativeLibrary.getInstance(\"name\") where findLibraryPath returns a path that Native.open fails to load: missing .so/.dll/.dylib file, wrong architecture (32/64-bit), missing transitive dependencies, or bad permissions.","commonSituations":"Native library not on java.library.path; missing system dependencies (e.g. libstdc++); cross-compiled binary mismatched with OS/arch; Android APK not packaging the .so; LD_LIBRARY_PATH not set.","solutions":["Verify the library file exists at the resolved path (check java.library.path and jna.library.path)","Set jna.library.path or LD_LIBRARY_PATH to the directory containing the library","Check file architecture matches the JVM (file libfoo.so shows x86-64 vs aarch64 etc.)","Install missing transitive dependencies with ldd/otool/Dependencies.exe","On Android, ensure the .so is packaged under jniLibs/<abi>/","Read the full list of accumulated UnsatisfiedLinkErrors; JNA keeps every failed attempt"],"exampleFix":"// before\nNativeLibrary.getInstance(\"mylib\");\n// after\nSystem.setProperty(\"jna.library.path\", \"/opt/myapp/lib\");\nNativeLibrary lib = NativeLibrary.getInstance(\"mylib\");","handlingStrategy":"try-catch","validationCode":"String path = NativeLibrary.processUtil.getLibc...; // or verify manually:\njava.io.File lib = new java.io.File(System.getProperty(\"java.library.path\").replace(':', java.io.File.pathSeparatorChar).split(java.io.File.pathSeparatorChar)[0], \"libmylib.so\");\nif (!lib.exists()) {\n    System.setProperty(\"jna.library.path\", \"/opt/myapp/lib\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    NativeLibrary lib = NativeLibrary.getInstance(\"mylib\");\n} catch (UnsatisfiedLinkError e) {\n    // check jna.library.path, architecture, dependencies\n    throw new RuntimeException(\"Native library mylib failed to load: \" + e.getMessage(), e);\n}","preventionTips":["Bundle native libraries with the app and set jna.library.path at startup","Match .so architecture to the JVM (check os.arch)","Verify dependencies with ldd before deployment","Log NativeLibrary.Archive/attempted paths on failure"],"tags":["jna","native-library","unsatisfiedlinkerror","library-loading"],"backgroundTag":"file-not-found","analyzedSha":"d036ad9781adad4b66693e8fa7098e4ac665e0a3","analyzedAt":"2026-09-12T06:50:59.239Z","contentChangedAt":"2026-09-12T06:50:59.239Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}