java native_error ai_generated true

java.lang.UnsatisfiedLinkError: no native library in java.library.path

ID: java/jni-error

Also available as: JSON · Markdown
75%Fix Rate
82%Confidence
55Evidence
2023-01-01First Seen

Version Compatibility

VersionStatusIntroducedDeprecatedNotes
17 active — — —

Root Cause

JNI errors occur when the JVM cannot load a native library (.so on Linux, .dll on Windows) required by Java code via System.loadLibrary(). Caused by missing native libraries, architecture mismatches, or missing native dependencies.

generic

Workarounds

  1. 85% success Set java.library.path or LD_LIBRARY_PATH to the directory containing the native library 
    1. Locate the .so file (e.g., find / -name 'libfoo.so' 2>/dev/null). 2. Add -Djava.library.path=/path/to/lib/dir to JVM arguments. 3. Alternatively, set LD_LIBRARY_PATH=/path/to/lib/dir in the environment. 4. Verify with 'ldd /path/to/libfoo.so' that all native dependencies of the .so are also satisfied. 5. Ensure the .so file matches the JVM architecture (amd64 vs aarch64).
  2. 80% success Install the missing native system library package required by the JNI binding 
    1. Read the UnsatisfiedLinkError message for the library name. 2. Use 'apt-file search libfoo.so' (Debian/Ubuntu) or 'yum whatprovides */libfoo.so*' (RHEL/CentOS) to find the package. 3. Install with 'apt-get install libfoo-dev' or 'yum install libfoo-devel'. 4. In Docker, add the package to the Dockerfile. 5. Restart the JVM.

Dead Ends

Common approaches that don't work:

  1. Copying the native library to a random directory without updating java.library.path 85% fail

    The JVM only searches directories listed in java.library.path (and LD_LIBRARY_PATH on Linux). Placing the .so file in an arbitrary directory will not make it discoverable.

  2. Using System.load() with a hardcoded absolute path in production code 65% fail

    Hardcoded paths break portability across environments (dev, staging, production, containers). The path is different on each machine and this approach fails in containerized deployments.

Error Chain

Leads to:
Preceded by:
Frequently confused with: