exceptions

java.lang.unsatisfiedlinkerror – How to handle Unsatisfied Link Error

In this tutorial we will discuss about Java’s UnsatisfiedLinkError and how to deal with it. The UnsatisfiedLinkError is a sub-class of the LinkageError class and denotes that the Java Virtual Machine (JVM) cannot find an appropriate native-language definition of a method declared as native. This error exists since the first release of Java (1.0) and is thrown only at runtime.

The UnsatisfiedLinkError is thrown when an application attempts to load a native library like .so in Linux, .dll on Windows or .dylib in Mac and that library does not exist. Specifically, in order to find the required native library, the JVM looks in both the PATH environment variable and the java.library.path system property.

A sample example that throws the aforementioned error is presented below:

UnsatisfiedLinkErrorExample.java:

public class UnsatisfiedLinkErrorExample {

     // Define a method that is defined externally.
     native void CFunction();

     // Load an external library, called "clibrary".
     static {
          System.loadLibrary("clibrary");
     }

     public static void main(String argv[]) {
          UnsatisfiedLinkErrorExample example = new UnsatisfiedLinkErrorExample();
          example.CFunction ();
     }
}

In this example, we define a native method called CFunction, which exists in the library under the name clibrary. In our main function we try to call that native method, but the library is not found and the following exception is thrown:

Exception in thread "main" java.lang.UnsatisfiedLinkError: no clibrary in java.library.path
     at java.lang.ClassLoader.loadLibrary(ClassLoader.java:1886)
     at java.lang.Runtime.loadLibrary0(Runtime.java:849)
     at java.lang.System.loadLibrary(System.java:1088)
     at main.java.Example.<clinit>(Example.java:10)

In order to resolve this issue, we must add the clibrary native library in the system path of our application.

How to deal with the UnsatisfiedLinkError

First of all we must verify that the parameter passed in the System.loadLibrary method is correct and that the library actually exists. Notice that the extension of the library is not required. Thus, if your library is named SampleLibrary.dll, you must pass the SampleLibrary value as a parameter.

Moreover, in case the library is already loaded by your application and the application tries to load it again, the UnsatisfiedLinkError will be thrown by the JVM. Also, you must verify that the native library is present either in the java.library.path or in the PATH environment library of your application. If the library still cannot be found, try to provide an absolute path to the System.loadLibrary method.

In order to execute your application, use the -Djava.library.path argument, to explicitly specify the native library. For example, using the terminal (Linux or Mac) or the command prompt (Windows), execute your application by issuing the following command:

java -Djava.library.path= "<path_of_your_application>" –jar <ApplicationJAR.jar>

Final comments on the Error

It is very important to discuss and notice that:

  • Using native methods make your Java application code platform dependent.
  • The System.loadLibrary method is equivalent as executing the Runtime.getRuntime().loadLibrary method.
  • The System.loadLibrary method shall be used in a static initializer block, in order to be loaded only once, when the JVM loads the class for the first time.

 
This was a tutorial about Java’s UnsatisfiedLinkError.

Sotirios-Efstathios Maneas

Sotirios-Efstathios (Stathis) Maneas is a PhD student at the Department of Computer Science at the University of Toronto. His main interests include distributed systems, storage systems, file systems, and operating systems.
Subscribe
Notify of
guest

This site uses Akismet to reduce spam. Learn how your comment data is processed.

5 Comments
Oldest
Newest Most Voted
Inline Feedbacks
View all comments
Sanil Jain
Sanil Jain
5 years ago

I am not able to resolve it. Please help me out

Shailjakant
Shailjakant
4 years ago

I’m still not able to resolve it :(

Salman Mirza
Salman Mirza
4 years ago

I’m still not able to resolve it

Samuel Kiragu
Samuel Kiragu
2 years ago

Thank You! This worked for me

wei
wei
2 months ago

if you don’t run this command, it won’t work.

export LD_LIBRARY_PATH=/path/to/the sofiles:$LD_LIBRARY_PATHLD_LIBRARY_PATH

Back to top button