IBM Support

WebSphere database connection exception java.lang.UnsatisfiedLinkError

Technical Blog Post


WebSphere database connection exception java.lang.UnsatisfiedLinkError



Problem: Selecting the WebSphere datasource test connection button results in a java.lang.UnsatisfiedLinkError

This exception typically results when using a type 2 JDBC driver and one or more of the following conditions occur:

  • Cannot locate the driver's required native libraries
  • The loaded version of the native libraries do not match the version of the driver
  • WebSphere Application Server's Java Virtual Machine (JVM) cannot load the drivers native libraries

Each of the above conditions is listed below. Note the DB2 type 2 JDBC Driver is used as an example, but be aware this problem can occur with any type 2 driver.


Cannot locate the required driver's native libraries

For UNIX, edit the root user's .profile and add a line to source the script to set up the required environment variables for DB2 (i.e. DB2INSTANCE, CLASSPATH, LD_LIBRARY_PATH, etc). For example: ./home/db2inst1/sqllib/db2profile

You can verify db2profile has been successfully sourced by stopping the WebSphere Application Server and adding the "env" command to the bottom of <WebSphere InstallRoot>/bin/ script file to print out the settings of all the environment variables used by the WebSphere Application Server's JVM and redirect the output to a file, for example: env > env.out

From the resulting env.out, verify the required environment variables used by the JDBC Driver are listed and have the correct settings, for example:


The library path environment variable is LD_LIBRARY_PATH for Linux & SUN , LIBPATH for AIX and SHLIB_PATH for HP-UX.
db2inst1 is the name of the DB2 instance in this example. Your DB2 instance may have a different name.
/home/db2inst1/ is the directory where DB2 is installed. Your DB2 installation path may be different.

From your WebSphere Administrative Console:

Resources > JDBC Provider > <Your JDBC Provider>
In the Configuration panel, specify the directory where the driver's native libraries are located in the Native Library Path field, for example:


The loaded version of the native libraries that do not match the version of the driver

The JDBC driver level does match the native libraries used or there are multiple copies of the JDBC driver on the JVM's system classpath. Even though the WebSphere configuration points to a specific driver, since the driver consist of multiple classes, the classloader can cause classes in the wrong driver's jar/zip to be invoked, which do not match the native libraries used.


WebSphere Application Server's Java Virtual Machine (JVM) cannot load the native libraries

WebSphere Application Server cannot load 64-bit libraries. Interrogate your DB2 version by issuing the command "db2level". This should produce an output similar to the following:

DB21085I Instance "DB2" uses "32" bits and DB2 code release "SQL08020" with level identifier "03010106". Informational tokens are "DB2 v8.1.7.445", "s040812", "WR21342", and FixPak "7".


Best Solution:

Change the WebSphere datasource from driver type 2 to driver type 4. Most users prefer the type 4 JDBC driver because it can be included with the application and does not depend on external libraries. Type 2 drivers always require a shared library because communication between the driver and the server is handled in the driver's non-Java component. The type 4 driver is pure java, does not use a database client or native libraries, and performs better than a type 2 driver.



title image (modified) credits: (cc) Some rights reserved by ClkerFreeVectorImages


[{"Business Unit":{"code":"BU004","label":"Hybrid Cloud"},"Product":{"code":"","label":""},"Component":"","Platform":[{"code":"","label":""}],"Version":"","Edition":""}]