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

Sotirios-Efstathios ManeasJanuary 16th, 2014Last Updated: October 5th, 2014

5 3,567 2 minutes read

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.