java native_error ai_generated true

java.lang.UnsatisfiedLinkError: /path/to/lib.so: libdep.so: cannot open shared object file: No such file or directory

ID: java/native-library-not-found

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

Version Compatibility

VersionStatusIntroducedDeprecatedNotes
17 active — — —

Root Cause

A native shared library (.so file) that a JNI binding depends on cannot be found on the system. The primary .so loads but its transitive native dependencies are missing from LD_LIBRARY_PATH or the system library directories.

generic

Workarounds

  1. 88% success Use ldd to identify all missing native dependencies and install them 
    1. Run 'ldd /path/to/libjni.so' to see all native dependencies and which are missing ('not found'). 2. For each missing library, find the package: 'apt-file search libmissing.so' or 'yum whatprovides */libmissing.so*'. 3. Install the package: 'apt-get install libmissing-dev'. 4. Run 'ldconfig' to refresh the library cache. 5. Verify with 'ldd' that all dependencies are now resolved.
  2. 85% success In Docker containers, install native dependencies in the Dockerfile and ensure the correct base image 
    1. Use a base image that includes common native libraries (e.g., eclipse-temurin:17 instead of alpine variants). 2. If using Alpine, install gcompat or musl equivalents. 3. Add RUN apt-get install -y libfoo-dev to the Dockerfile. 4. Run RUN ldconfig after installing libraries. 5. Test the container locally before deploying.

Dead Ends

Common approaches that don't work:

  1. Installing only the main library without its native dependencies 80% fail

    Native libraries have their own dependency chains (visible via ldd). If a dependency .so is missing, the main .so cannot be loaded even if it is present. All transitive native dependencies must be satisfied.

  2. Creating symlinks to random library versions to satisfy the dependency 70% fail

    Symlinking to an incompatible version (e.g., libfoo.so.2 -> libfoo.so.3) may load but can cause segfaults or undefined behavior due to ABI incompatibility. The correct version must be installed.

Error Chain

Leads to:
Preceded by:
Frequently confused with: