Monday, March 3, 2014

java.lang.UnsatisfiedLinkError: Setting Environment Variable

This UnsatisfiedLinkError Error is thrown to indicate that an appropriate native language definition of a method declared native cannot be found by the Java Virtual Machine.
java.lang.UnsatisfiedLinkError: Can't load library:[1]
When a Java application loads a native library using the System.loadLibrary() method, the java.library.path is scanned for the specified library. If the JVM is not able to detect the requested library, it throws an UnsatisfiedLinkError.[15]

In this article, we will look at setting environment variables to revolve this kind of errors assuming missing libraries are installed correctly and have appropriate permissions and ownership.

Tell Whom Where to Find What

Different environment variables differ in the following aspects:
  • Tell whom where to find what
Here, we have summarized environment variables based on the above criteria:

Environment Variable WhomWhatDescription
Windows/bin When a command is entered in a command shell or a system call is made by a program to execute a program, the system first searches the current working directory and then searches the path, examining each directory from left to right, looking for an executable filename (EXE, COM, BAT, or CMD) that matches the command name given.
/libSet the shared library path environment variable.
Linux/binTells the shell which directories to search for executable files in response to commands issued by a user.[2]
LIBPATH AIX /lib Set the shared library path environment variable.[16]
  • In Unix, the environment variable LD_LIBRARY_PATH or its variants (see next section) is a colon-separated set of directories where libraries should be searched for first, before the standard set of directories
  • LD_LIBRARY_PATH is handy for development and testing
WebLogic,[9] IDEs,[8Other ProgramsJRE (Java runtime environment)
  • Note that java.home is always there inside JVM, whereas JAVA_HOME exists mainly in your shell environment and you may pass it to JVM as a system property.[4]
  • You can use it to set the PATH variable. This is very convenient, because if you install another version of the JDK, all you need to do is to update your JAVA_HOME, without having to touch the PATH.[14]
  • If the application server ships with a JVM, then the JAVA_HOME environment variable must be set to reference it.
classpath or CLASSPATHJava Launcher or Java CompilerUser-defined classes and packages[10]
  • Classpath in Java is path to directory or list of directory which is used by ClassLoaders[11,20] to find and load class in Java program
  • By default only the packages of the JDK standard API and extension packages are accessible without needing to set where to find them.[7]
  • The path for all user-defined packages and libraries must be set in the command-line (or in the Manifest associated with the Jar file containing the classes).
  • Instead of setting the  classpath on the command lines, the environment variable named CLASSPATH may be used.

Here are the summarized system properties used during class loading based on the above criteria:

System PropertyWhomWhatDescription
JVMnative librariesThe Java Virtual Machine (JVM) uses the java.library.path property in order to locate native libraries. This property is part of the system environment used by Java, in order to locate and load native libraries used by an application.  Note that java.library.path is linked to LIBPATH or PATH or LD_LIBRARY_PATH, depending on the OS.
JVMnative librariesThe Java Virtual Machine (JVM) uses the sun.boot.library.path property in order to locate native libraries. This property is part of the system environment used by Java, in order to locate and load native libraries used by an application.  Note that sun.boot.library.path is searched before java.library.path.


If you have set your shared-library-path environment variable[3,4,5]  and system properties[15] correctly, you should be able to resolve this error. Read [1,15] for more information.
java.lang.UnsatisfiedLinkError: Can't load library:[1]

When you set environment variables, you want to consider which user(s) you want to set them for. For example, you can set environment variables for either your user only, or for all users (System variables). If you run Java applications in a WebLogic server, oftentimes you set environment variables such as LD_LIBRARY_PATH, etc. in the setDomainEnv.cmd/sh script (see also setWLSEnv.cmd/sh script) of a WebLogic domain.[6] In this way, you can avoid setting environment variables in the global scope, which may affect other applications.

As you may have noticed, there are idiosyncrasies of environment variables among platforms. For example, to set the shared-library-path environment variable, you do this differently on different platforms:

Operation System
Environment Variable
Solaris and Linux


  1. Can't load library
  2. PATH Definition
  3. Purpose of JAVA_HOME and PATH environment variables ?
  4. Why do you need JAVA_HOME environment variable?
    • To ensure that your Java programs pick the right Java.exe
    • To specify which installed versions of Java as default
    • To use tools/libraries only available in JDK
  5. Shared Libraries
  6. weblogic.Server Command-Line Reference
  7. classpath (Java)
  8. Configuring JDeveloper with a Different JDK (Xml and More)
  9. Configuring WebLogic Server with a Different JVM (Xml and More)
  10. Java Throwable: ClassNotFoundException vs. NoClassDefFoundError (Xml and More)
  11. WebLogic's Classloading Framework (Xml and More)
  12. Using the Classloader Analysis Tool (CAT)
  13. WebLogic Server (WLS) Support Pattern: Investigating Different Classloading Issues (Doc ID 1572862.1)
  14. Installing the JDK Software and Setting JAVA_HOME
  15. java.library.path – What is it and how to use 
  16. LIBPATH: Setting library search paths 
  17. Setting up the ODWEK application development environment
  18. java classpath separator  
    • In Unix/Linux/Solaris
      • CLASSPATH are separated by colons(:)
    • In Windows
      • CLASSPATH are separated by semicolons(;) 
  19. If the message says "java.lang.UnsatisfiedLinkError: no lwjgl in java.library.path". The "lwjgl" is interpreted in a platform-dependent way:
    • On Windows
      • it means LWJGL.DLL . 
    • On Linux and many other UNIX variants
      • it means ""
      • On other platforms
        • it may mean something else
  20. Error: Could not find or load main class weblogic.Server
    • Check your classpath or CLASSPATH
  21. Java Evolution: JDK and JRE File Structure (Xml and More)