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

Technote (troubleshooting)


Problem(Abstract)

Your WebSphere MQ Java™ or JMS application attempts to connect to a local queue manager but fails with a java.lang.UnsatisfiedLinkError.

Cause

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)

    ...

Resolving the problem

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.5, 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.


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 and 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 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:



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:



    Using setmqenv

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


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



    Setting the Java library path manually

    sh> . /opt/mqm75/bin/setmqenv -s
    sh> java -Djava.library.path=/opt/mqm75/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.



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:



    Using setjmsenv64 and setjmsenv

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

    sh> . /opt/mqm/bin/setjmsenv
    sh> java -Djava.library.path=/opt/mqm/java/lib 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:


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



    Setting the Java library path manually

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


Related information

A Japanese translation is available

Cross reference information
Segment Product Component Platform Version Edition
Application Servers WebSphere Application Server Java Message Service (JMS) AIX, HP-UX, IBM i, Linux, Solaris, Windows, z/OS 8.5.5, 8.5, 8.0, 7.0, 6.1, 6.0

Product Alias/Synonym

WMQ MQ

Rate this page:

(0 users)Average rating

Add comments

Document information


More support for:

WebSphere MQ
Java

Software version:

5.3, 6.0, 7.0, 7.1, 7.5

Operating system(s):

AIX, HP NonStop, HP-UX, Linux, OpenVMS, Solaris, Windows

Software edition:

All Editions

Reference #:

1248900

Modified date:

2013-06-14

Translate my page

Machine Translation

Content navigation