java.lang.UnsatisfiedLinkError occurs when connecting to a queue manager

In order to establish a connection to a local queue manager, often called a "bindings" connection, the WebSphere MQ Java and JMS classes must load one or more native libraries. When your Java virtual machine cannot find these native libraries, the connection attempt fails with an exception similar to the following:

java.lang.UnsatisfiedLinkError: mqjbnd (A file or directory in the path name does not exist.)
at java.lang.ClassLoader.loadLibraryWithPath(ClassLoader.java:994)
at java.lang.ClassLoader.loadLibraryWithClassLoader(ClassLoader.java:958)
at java.lang.System.loadLibrary(System.java:453)
at com.ibm.mq.jmqi.local.LocalMQ.loadLib(LocalMQ.java:1055)
...

In order to establish a bindings connection to a local queue manager, you must have installed WebSphere MQ on the machine where your Java or JMS application is running. If WebSphere MQ is not installed locally, or if the target queue manager is on a different system, you must use a client connection instead.

If the queue manager is running on the local system, your environment settings must be modified so your Java application environment can find the WebSphere MQ native libraries. Follow the instructions below for applications deployed in WebSphere Application Server and for applications in other Java environments:

WebSphere Application Server V8.5, V8.0 and V7.0 Applications

WebSphere Application Server v7.0 and later uses the WebSphere MQ resource adapter to connect to queue managers. If your application is deployed to WebSphere Application Server, follow the instructions in the Information Center to set the "Native library path" on the resource adapter. These links also describe how to set the MQ_INSTALL_ROOT property on the launchClient command line if your application is running in the client container.

• WebSphere Application Server V8.5 setting native library information
• WebSphere Application Server V8.0 setting native library information
• WebSphere Application Server V7.0 setting native library information

The value you use should be the java/lib64 subdirectory of your WebSphere MQ installation, if you are using a 64-bit Java virtual machine, or the java/lib subdirectory for 32-bit Java virtual machines. Please note that WebSphere MQ V7.1 and later can be installed in different locations than these defaults:

• AIX (64- and 32-bit)
  
  /usr/mqm/java/lib64
  /usr/mqm/java/lib

• HP-UX, Linux & Solaris (64- and 32-bit)
  
  /opt/mqm/java/lib64
  /opt/mqm/java/lib

• Windows (64- and 32-bit)
  
  C:\Program Files (x86)\IBM\WebSphere MQ\java\lib64
  C:\Program Files (x86)\IBM\WebSphere MQ\java\lib

WebSphere Application Server V6.1 and V6.0.2 Applications

WebSphere Application Server V6.1 and V6.0.2 do not use the WebSphere MQ resource adapter. Instead, you must update the MQ_INSTALL_ROOT variable after installing WebSphere MQ on the machine, as documented in the Information Center:

• Websphere Application Server V6.1 interoperation with WebSphere MQ
• WebSphere Application Server V6.0.2 interoperation with WebSphere MQ

WebSphere MQ V7.5 and V7.1 Applications in Other Environments

First, set your environment using the setmqenv command, as described in the WebSphere MQ Information Centers:

• WebSphere MQ V7.5 native library information
• WebSphere MQ V7.5 setmqenv command

• WebSphere MQ V7.1 native library information
• WebSphere MQ V7.1 setmqenv command

In order for your Java virtual machine to find the necessary native libraries, you must pass additional options to the setmqenv command. Use either the -k or -l (ell) option to modify your library path, along with the -x option to choose 32- or 64-bit libraries, depending on your Java virtual machine. On UNIX and Linux systems, be sure to source the setmqenv command, for example:

sh>   . /opt/mqm75/bin/setmqenv -n Installation1 -l -x64

If you do not wish to modify your library path environment variables, you can use Java command line arguments to indicate the location of the WebSphere MQ native libraries, for example:

sh> . /usr/mqm71/usr/mqm/bin/setmqenv -s

sh> java -Djava.library.path=/opt/mqm/java/lib64 YourApp

WebSphere MQ V7.0 and V6.0 Applications in Other Environments

First, set your environment using the setmqenv64 or setjmsenv commands, as described in the WebSphere MQ Information Centers. Note that setjmsenv64 is available only in WebSphere MQ V7.0.

• WebSphere MQ V7.0 native library information
• WebSphere MQ V7.0 environment variables

• WebSphere MQ V6.0 native library information
• WebSphere MQ V6.0 environment variables

On UNIX and Linux systems, be sure to source the setjmsenv64 or setjmsenv commands. Next, use the Java command line arguments to indicate the location of the WebSphere MQ native libraries, for example:

sh> . /opt/mqm/bin/setjmsenv64

sh> java -Djava.library.path=/opt/mqm/java/lib64 YourApp

WebSphere MQ V7.0 users on AIX should review APAR IZ84448, especially when using a 64-bit Java virtual machine. The APAR describes how to use the dltmqlnk program to ensure the right 32- or 64-bit native libraries are loaded. It also documents the new com.ibm.mq.cfg.jmqi.libpath property added in WebSphere MQ V7.0.1.5 to help resolve problems loading native libraries.

WebSphere MQ V5.3 Applications in Other Environments

Since WebSphere MQ V5.3 does not provide any scripts to set your CLASSPATH, library path, or other environment variables for Java, follow the instructions in the Using Java manual to do so manually:

• WebSphere MQ Using Java

After setting your environment, use the java command line arguments to indicate the location of the WebSphere MQ native libraries, for example:

C:\> java -Djava.library.path="C:\Program  Files  (x86)\IBM\WebSphere  MQ\java\lib" YourApp