Fixing the Error “java lang UnsatisfiedLinkError” Custom DLL Load in Java

In this article, we will learn different approaches to fixing the ‘java lang UnsatisfiedLinkError’ error in Java, when we need to load custom DLL Libraries! If you’ve ever encountered the dreaded “java.lang.UnsatisfiedLinkError” error in a Java application, you’re not alone. This error occurs when Java attempts to load a native library (a Dynamic Link Library or DLL in the Windows world) and cannot find the library or encounters issues during the loading process.

1. Understanding the “java.lang.UnsatisfiedLinkError” Error

Before we dive into solutions, let’s understand what this error message is telling us. When Java encounters this error, it means it’s trying to link (or connect) a Java application with a native library, usually written in C or C++, but it can be any language that can be compiled into a shared library. This linkage is done through a mechanism called Java Native Interface (JNI).

The error message typically looks something like this:

• java.lang.UnsatisfiedLinkError: This is the exception type, indicating that a linkage error occurred.
• no nonexistentlibrary in java.library.path: This part of the error message tells you that Java couldn’t find the native library in the specified library path.

2. Reasons for the Error

There are several reasons why you might encounter this error:

• Library Not in the Library Path: The most common reason is that the native library is not in the directory specified in the java.library.path system property.
• Library Name Mismatch: The name of the library might not match what Java expects. For example, if your Java code is looking for library.dll, but the file is named liblibrary.so (on Linux) or library.dylib (on macOS), it won’t find it.
• Library Dependencies: The library you’re trying to load may have dependencies on other libraries that are missing or not correctly linked.
• Architecture Mismatch: You might be trying to load a 32-bit library into a 64-bit JVM or vice versa.

Now, let’s explore how to fix these issues using custom DLL loading techniques.

3. Replicating the “java.lang.UnsatisfiedLinkError” Error

To gain a deeper understanding of fixing the ‘java lang UnsatisfiedLinkError’ error in Java when we need to load custom DLL Libraries and to demonstrate the solutions discussed in this article, we will replicate the error intentionally. We’ll go through the process step by step:

3.1 Create a Java Class

Let’s start by creating a simple Java class that attempts to load a non-existent native library. Open your favorite text editor or Integrated Development Environment (IDE) and create a new Java class named NativeLibraryDemo.java.

public class NativeLibraryDemo {
    static {
        System.loadLibrary("nonexistentlibrary");
    }

    public static void main(String[] args) {
        System.out.println("Application started.");
    }
}

In this class, we use System.loadLibrary("nonexistentlibrary") to attempt to load a native library named “nonexistentlibrary.”

3.2 Compile the Java Class

Next, compile the Java class using the javac command:

javac NativeLibraryDemo.java

3.3 Run the Java Application

Now, try to run the Java application:

java NativeLibraryDemo

You should see the following error message, indicating that Java cannot find the “nonexistentlibrary” native library:

This error replicates the “java.lang.UnsatisfiedLinkError” scenario, where Java is unable to locate the required native library.

4. Custom DLL Loading Techniques

4.1 Specify the Library Path

Specifying the library path is a platform-independent technique for fixing the “java.lang.UnsatisfiedLinkError” error. This approach ensures that Java knows where to look for the native library. Below, I’ll break down how to specify the library path for various platforms: Windows, Linux, and macOS.

4.1.1 Specifying the Library Path on Windows

On Windows, the library path is specified using the -Djava.library.path flag when running a Java application. Follow these steps to specify the library path:

1. Compile Your Java Code: Make sure your Java code is correctly compiled.
2. Locate Your DLL File: Find the directory containing the native DLL file you want to load. Note the full path to this directory.
3. Run Your Java Application: Use the java command with the -Djava.library.path flag to specify the library path. Replace /path/to/dll/directory with the actual path to your DLL directory and YourApp.jar with your application’s JAR file:

   java -Djava.library.path=/path/to/dll/directory -jar YourApp.jar

For example, if your DLL is in C:\MyProject\dll, the command might look like this:

   java -Djava.library.path=C:\MyProject\dll -jar YourApp.jar

4. Run Your Application: Your Java application should now run without encountering the “java.lang.UnsatisfiedLinkError” error since it knows where to find the DLL.

4.1.2 Specifying the Library Path on Linux

On Linux, the process is similar to Windows but with some minor differences in path syntax. Here’s how to specify the library path:

1. Compile Your Java Code: Ensure your Java code is correctly compiled.
2. Locate Your Shared Library (SO) File: Find the directory containing the shared library (SO file) you want to load. Note the full path to this directory.
3. Run Your Java Application: Use the java command with the -Djava.library.path flag to specify the library path. Replace /path/to/so/directory with the actual path to your SO directory and YourApp.jar with your application’s JAR file:

   java -Djava.library.path=/path/to/so/directory -jar YourApp.jar

For example, if your SO file is in /home/user/MyProject/so, the command might look like this:

   java -Djava.library.path=/home/user/MyProject/so -jar YourApp.jar

4. Run Your Application: Your Java application should run without encountering the “java.lang.UnsatisfiedLinkError” error.

4.1.3 Specifying the Library Path on macOS

On macOS, the process is quite similar to Linux, but with the use of DYLD_LIBRARY_PATH instead of LD_LIBRARY_PATH. Here are the steps:

1. Compile Your Java Code: Make sure your Java code is correctly compiled.
2. Locate Your Dylib File: Find the directory containing the dynamic library (dylib file) you want to load. Note the full path to this directory.
3. Run Your Java Application: Use the java command with the -Djava.library.path flag to specify the library path. Replace /path/to/dylib/directory with the actual path to your dylib directory and YourApp.jar with your application’s JAR file:

   java -Djava.library.path=/path/to/dylib/directory -jar YourApp.jar

For example, if your dylib file is in /Users/user/MyProject/dylib, the command might look like this:

   java -Djava.library.path=/Users/user/MyProject/dylib -jar YourApp.jar

4. Run Your Application: Your Java application should run without encountering the “java.lang.UnsatisfiedLinkError” error.

By specifying the library path as demonstrated above, you ensure that Java can locate and load the necessary native libraries, making your Java application cross-platform compatible and free from the “java.lang.UnsatisfiedLinkError” error.

4.2 Renaming the DLL

If the library name mismatch is the problem, you can rename the DLL to match what Java expects. For example, if your Java code is looking for library.dll, you can rename liblibrary.dll to library.dll.

4.3 Dependency Resolution

Dependency resolution is an essential aspect of fixing the “java.lang.UnsatisfiedLinkError” error when working with native libraries in Java. This step ensures that any libraries or dependencies required by the native library you’re trying to load are available and correctly linked. Let’s dive deeper into this concept:

4.3.1 What Are Dependencies in Native Libraries?

In the context of native libraries, dependencies refer to other libraries or files that your primary native library relies on to function correctly. These dependencies can be other native libraries, shared objects (SO) files on Linux, dynamic link libraries (DLL) on Windows, or dynamic libraries (dylib) on macOS. They contain code and functions that are used by your main native library.

Here’s a simplified example to illustrate the concept:

Suppose you have a Java application that loads a native library called mylibrary.dll. This mylibrary.dll may depend on another native library, let’s call it dependency.dll, to perform certain tasks. If dependency.dll is missing or not accessible, you might encounter the “java.lang.UnsatisfiedLinkError” error.

4.3.2 How to Resolve Dependencies

To resolve dependencies and prevent the “java.lang.UnsatisfiedLinkError” error, consider the following steps:

Identify Dependencies:

Begin by identifying all the dependencies required by your main native library. You can usually find information about these dependencies in the documentation provided with the library or through tools like ldd (Linux) or Dependency Walker (Windows).

Ensure Dependencies are Present:

Make sure that the required dependencies are present in a location where the operating system can find them. This can be in the same directory as your main native library or in a directory specified in the system’s library search path.

• Same Directory: Placing the dependencies in the same directory as your main native library ensures that they are easily discoverable. When your Java application loads mylibrary.dll, it will also look in the same directory for any required dependencies like dependency.dll.
• System Library Path: Alternatively, you can place the dependencies in a directory that is part of the system’s library search path. This can be configured through environment variables like LD_LIBRARY_PATH on Linux or PATH on Windows. However, this approach may require administrative privileges on some systems.

Use System Properties (Java)

When running your Java application, you can specify the library path using the -Djava.library.path flag, as mentioned in the previous section. This flag allows you to set the directory where Java should look for native libraries and their dependencies.

Distribute Dependencies with Your Application

If you have control over the distribution of your Java application and its associated native libraries, consider packaging the dependencies along with your application. This approach ensures that the necessary dependencies are always available, regardless of the target system’s configuration.

4.4 Architectural Compatibility

Architectural compatibility, often referred to as bitness compatibility, is a critical aspect of ensuring that your Java application can successfully load and use native libraries. It revolves around the architecture of both the Java Virtual Machine (JVM) and the native library, specifically whether they are 32-bit or 64-bit.

Here’s a breakdown of key architectural considerations:

JVM Bitness:

• 32-bit JVM: A 32-bit JVM is designed to work with 32-bit native libraries. It can execute Java applications and load native libraries that are also compiled as 32-bit.
• 64-bit JVM: A 64-bit JVM is compatible with both 32-bit and 64-bit native libraries. It can run Java applications and load native libraries in either architecture.

Native Library Bitness:

• 32-bit Native Library: A native library compiled as 32-bit is designed to work with 32-bit JVMs. Attempting to load a 32-bit native library into a 64-bit JVM will result in the “java.lang.UnsatisfiedLinkError” error.
• 64-bit Native Library: A native library compiled as 64-bit is compatible with both 32-bit and 64-bit JVMs. It can be loaded by either architecture of JVM.

4.4.1 Common Scenarios and Solutions

To ensure architectural compatibility and avoid the “java.lang.UnsatisfiedLinkError” error, consider these common scenarios and solutions:

Scenario 1: Running a 64-bit JVM with a 32-bit Native Library

Problem: You have a 64-bit JVM, but you’re attempting to load a 32-bit native library.

Solution: You have a few options:

• Use a 32-bit JVM: Install and use a 32-bit JVM to run your Java application. This allows you to load 32-bit native libraries without issues.
• Recompile the Native Library: If possible, recompile the native library as a 64-bit version. This ensures compatibility with your 64-bit JVM.

Scenario 2: Running a 32-bit JVM with a 64-bit Native Library

Problem: You have a 32-bit JVM, but you’re trying to load a 64-bit native library.

Solution: Similar to the previous scenario, you have a couple of options:

• Use a 64-bit JVM: If your system supports it, install and use a 64-bit JVM to run your Java application. This allows you to load 64-bit native libraries without issues.
• Recompile the Native Library: If possible, recompile the native library as a 32-bit version to match your 32-bit JVM.

Scenario 3: Running a 64-bit JVM with a Compatible Native Library

Scenario: You have a 64-bit JVM, and your native library is already compiled as 64-bit.

Solution: In this case, you’re in an architecturally compatible setup, and your Java application should be able to load and use the native library without any issues.

4.4.2 Verifying JVM Architecture

To check the architecture (bitness) of your JVM, you can run the following Java code snippet:

public class JVMArchitecture {
    public static void main(String[] args) {
        String arch = System.getProperty("sun.arch.data.model");
        System.out.println("JVM Architecture: " + arch + "-bit");
    }
}

Running this code will print the bitness of your JVM (e.g., “32-bit” or “64-bit”) to the console.

By understanding and ensuring architectural compatibility between your JVM and native libraries, you can effectively prevent the “java.lang.UnsatisfiedLinkError” error and ensure that your Java application runs smoothly with the desired native libraries, regardless of the platform and architecture.

4.5 Custom DLL Loading

In some cases, you may need to load dependencies programmatically within your Java code using custom loading techniques. This approach provides fine-grained control over the loading process and allows you to handle errors gracefully.

Here’s a simplified example of how you can load a dependency dynamically in Java:

public class NativeLibraryDemo {
    static {
        try {
            System.loadLibrary("mylibrary");
            System.loadLibrary("dependency");
        } catch (UnsatisfiedLinkError e) {
            // Handle the error here
        }
    }

    public static void main(String[] args) {
        // Your code that uses mylibrary and its dependency
    }
}

By following these steps and ensuring that all dependencies are accessible, you can effectively resolve dependency-related issues that may lead to the “java.lang.UnsatisfiedLinkError” error, allowing your Java application to run smoothly.

5. Java Classloaders Error

Java classloaders are responsible for loading classes into the Java Virtual Machine (JVM). Each classloader has its own isolated namespace, which means that classes loaded by different classloaders cannot see each other. This is a useful feature for security and performance reasons.

However, it can also lead to problems if you are trying to load a native library that is already loaded by another classloader. When Java tries to load a native library, it checks to see if the library is already loaded by another classloader. If it is, Java will throw the “Library Already Loaded by Another Classloader” error.

This error can occur for a number of reasons, such as:

• You are using two different versions of the same library, and each version is loaded by its own classloader.
• You are using a third-party library that loads native libraries without your knowledge.
• You are loading the same native library from different threads in your application.

To fix the “Library Already Loaded by Another Classloader” error, you need to unload the library from the other classloader before loading it in your Java program. This can be done using the ClassLoader.unloadLibrary() method.

For example, the following code will unload the library mylibrary from the current classloader:

ClassLoader classLoader = ClassLoader.getSystemClassLoader();
classLoader.unloadLibrary("mylibrary");

Once the library has been unloaded from the other classloader, you can load it in your Java program using the System.loadLibrary() method.

If you are unable to identify the classloader that is loading the library, you can try running your Java program with the -verbose:class option. This will output verbose information about the classes that Java is loading. This information may help you to identify the class that is loading the native library that you are having problems with.

If you are still unable to fix the error, you may need to contact the developer of the library you are using for more information.

Here are some best practices for avoiding the “Library Already Loaded by Another Classloader” error:

• Use a dependency management tool, such as Maven or Gradle, to manage the dependencies of your application. This will help to ensure that you are using the correct version of each library and that you are not accidentally loading the same library from multiple classloaders.
• Be careful when using third-party libraries. Some third-party libraries may load native libraries without your knowledge. If you are unsure whether a third-party library is loading native libraries, you can check the documentation for the library.
• If you are using native libraries in your application, make sure to unload them when you are finished using them. This can be done using the ClassLoader.unloadLibrary() method.

By following these best practices, you can help to avoid the “Library Already Loaded by Another Classloader” error.

6. Editing Java’s Security Policy

Java security policy can be a problem for the topic of loading native libraries from different classloaders because it can prevent you from unloading native libraries from other classloaders.

By default, the Java Security Manager will not allow you to unload native libraries from other classloaders. This is because unloading a native library could potentially destabilize the JVM.

However, if you are using native libraries in your application, you may need to unload them in order to fix the “Library Already Loaded by Another Classloader” error. To do this, you need to grant the Java Security Manager permission to unload native libraries.

You can grant this permission by adding the following line to your Java security policy file:

grant permission java.lang.ClassLoader "ClassLoader.unloadLibrary";

Once you have granted this permission, you will be able to unload native libraries from other classloaders using the ClassLoader.unloadLibrary() method.

However, it is important to note that granting this permission could potentially destabilize the JVM. Therefore, you should only grant this permission if you are sure that you need to do so.

Here are some additional things to keep in mind when using Java security policy:

• Java security policy is a complex topic, and it is important to understand the implications of any changes you make to your security policy file.
• If you are unsure about how to change your security policy file, you should consult with a Java security expert.
• You should also test your application thoroughly after making any changes to your security policy file to make sure that it is still working correctly.

In addition to the above, here are some other potential problems that can arise when loading native libraries from different classloaders:

• Version conflicts: If two different classloaders are loading the same native library, but different versions of the library, this can lead to problems. For example, one version of the library may introduce a new API that is not available in the other version of the library. This can cause your application to crash or behave unexpectedly.
• Resource conflicts: If two different classloaders are loading the same native library, and both classloaders are trying to access the same resources, such as files or memory, this can lead to problems. For example, one classloader may try to write to a file that the other classloader is reading from. This can corrupt the file or cause your application to crash.
• Security vulnerabilities: If a native library is loaded by a classloader that has a lower security context than the classloader that is trying to use the library, this could potentially allow the library to execute malicious code.

To avoid these problems, it is important to carefully consider how you are loading native libraries in your application. If you are using multiple classloaders, you should make sure that they are all loading the same versions of the same native libraries. You should also make sure that the classloaders are not trying to access the same resources at the same time. And finally, you should make sure that the classloaders have the appropriate security context to load and use the native libraries.

If you are unsure about how to safely load native libraries from different classloaders, you should consult with a Java security expert.

7. Conclusion

The “java lang UnsatisfiedLinkError” error in Java can be difficult fixing, but with a clear understanding of its causes and the appropriate solutions, you can resolve it and get your Java application working smoothly when we load custom native dll libraries. Whether you need to adjust the library path, rename the DLL, manage dependencies, or use custom loading techniques, you now have the tools to tackle this error head-on. Remember to test your changes thoroughly to ensure your application functions as expected with the custom DLL loading approach you choose.

8. Download the Source Code

This was an article on fixing the ‘java lang UnsatisfiedLinkError’ error in Java when we need to load custom DLL Libraries!

Do you want to know how to develop your skillset to become a Java Rockstar?

Subscribe to our newsletter to start Rocking right now!

To get you started we give you our best selling eBooks for FREE!

1. JPA Mini Book

2. JVM Troubleshooting Guide

3. JUnit Tutorial for Unit Testing

4. Java Annotations Tutorial

5. Java Interview Questions

6. Spring Interview Questions

7. Android UI Design

and many more ....

I agree to the Terms and Privacy Policy

Sign up

Thank you!

We will contact you soon.