How to Fix Failed to connect to queue manager - WebSphere MQ Error in Java? Example

"Failed to connect to queue manager" error comes in WebSphere MQ if any Client like a Java program is not able to connect to the MQ server due to any reason. The reason is actually identified by reason code in error message e.g. code 2397 comes when SSL is enabled between client and server and Java client is not able to connect to the server due to unknown or expired SSL certificates. If you are working in a Java application that is using WebSphere MQ for messaging over SSL then you are bound to face some setup, certificate, and keystore vs truststore related error. 

For first-timers understanding SSL and MQ errors is a nightmare, forget about solving them. I have gone through that and after spending hours on Google and Websphere MQ documentation, I managed to solve some of the problems we face while connecting to MQ over SSL from our Java application. 

In this article, I am listing down these errors and exceptions and their cause and solution for everyone's benefit. Next time you face any MQ SSL issue, hopefully, you will find the right solution to solve these tricky errors. In this tutorial we will mainly look at three errors :

• Unable to find valid certification path to requested target
• JMSWMQ2020: Failed to connect to the queue manager
• Remote SSL peer name error for channel 'ABC.XYZ'

I have mostly encountered these while working with Java application which was connecting to other legacy systems using MQ for sending and receiving XML files, but useful to anyone who is using over MQ over SSL.

SSL handshake failed: unable to find valid certification path to requested target

The first problem we face was due to the expiry of SSL certificates which our Java client is using to connect to the MQ series. Here is the exact exception :

Error :
SSL handshake failed. [1=javax.net.ssl.SSLHandshakeException[sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target

Cause: server was moved to different SSL signer certificates, personal certificates on keystore was expired.

Solution: If personal certificates are expired then you need to create new valid personal certificates and add them into the keystore. Also, add new signer certificates into the trust store which is used by the server. This would be required during an SSL handshake. 

Once we updated our Java application's truststore and keystore this error was solved. It took me a long time to understand and fix this error because I wasn't aware of the exact difference between keystore and truststore and how exactly they are used during the SSL handshake process.

JMSWMQ2020: Failed to connect to the queue manager

This error was also related to the previous problem but it confuses a lot and we spent time to see if the queue is available, it allows connection and other properties because it doesn't tell anything about the actual cause, which is expired SSL certificates. If you are completely new to SSL and Java then I would also suggest reading my earlier tutorial about SSL, Certificate, and Java to understand more.

Error
com.ibm.msg.client.jms.DetailedJMSException: JMSWMQ2020: Failed to connect to queue manager
Caused by: com.ibm.mq.MQException: JMSCMQ0001: WebSphere MQ call failed with compcode '2' ('MQCC_FAILED') reason '2397' ('MQRC_JSSE_ERROR').
        at com.ibm.msg.client.wmq.common.internal.Reason.createException(Reason.java:223)


Cause: Code 2397 comes when SSL is enabled between MQ client and server but SSL handshake is failed due to certificates issues e.g. different signer certs on the client and server-side or expired certificates on the client and server-side.

Solution:  Once we added a new set of SSL certificates in keystore and truststore and also deployed in MQ server this error was solved. BTW, always check for MQ Error code, because that's more precise then error message and MQ use different error code for different exceptions. 

For Example, if both the MQ client and server have the correct set of certificates, and you are still not able to connect others, then there could be an issue with the SSL Peer setup. The common name, ("cn" field in your SSL certificate) of client's personal SSL certificates are required to be added as SSLPEER on the server side, and if that's not set up, SSL connection will not establish and MQ will give you following error :

Caused by: com.ibm.mq.MQException: JMSCMQ0001: 
WebSphere MQ call failed with compcode '2' ('MQCC_FAILED') 
reason '2059' ('MQRC_Q_MGR_NOT_AVAILABLE').
        at com.ibm.msg.client.wmq.common.internal.Reason
.createException(Reason.java:223)
Caused by: com.ibm.mq.jmqi.JmqiException: CC=2;RC=2059;AMQ9643:
 Remote SSL peer name error for channel 'ABC.XYZ'
        at com.ibm.mq.jmqi.remote.internal.system.RemoteConnection.
analyseErrorSegment(RemoteConnection.java:4607)
        at com.ibm.mq.jmqi.remote.internal.system.RemoteConnection.
receiveTSH(RemoteConnection.java:3086)
        at com.ibm.mq.jmqi.remote.internal.system.RemoteConnection.
initSess(RemoteConnection.java:1532)
        at com.ibm.mq.jmqi.remote.internal.system.RemoteConnection.
connect(RemoteConnection.java:1201)
        at com.ibm.mq.jmqi.remote.internal.system.RemoteConnectionPool.
getConnection(RemoteConnectionPool.java:354)
        at com.ibm.mq.jmqi.remote.internal.RemoteFAP
.jmqiConnect(RemoteFAP.java:1662)

You can check here the MQ code for the reason is 2059, which is different from the previous code 2397. So paying close attention to the MQ reason code, among clutters of Exception Stack trace is key to identifying the reason behind failure.

SSL Peer Failure

When you enable SSL between client and Server in MQ, you also need to add SSL Peer in WebSphere MQ Server Side. This SSL Peer is a common name (CN) from client applications personal certificates e.g. for the following common name :

Owner: CN=TEST_CERTS, OU=RES, O=APP, L=London, ST=London, C=UK

SSLPeer entry should be :

SSLPEER(CN=TEST_CERTS, OU=RES, O=APP, L=London, ST=London, C=UK)

If SSLPeer is not setup or common name from client's personal certificate is not matching with SSLPEER then WMQ will throw following error, when Java Client will try to connect to MQ server :

Caused by: com.ibm.mq.MQException: JMSCMQ0001: 
WebSphere MQ call failed with compcode '2' ('MQCC_FAILED')
reason '2059' ('MQRC_Q_MGR_NOT_AVAILABLE').

        at com.ibm.msg.client.wmq.common.internal.Reason.
createException(Reason.java:223)

Caused by: com.ibm.mq.jmqi.JmqiException: CC=2;RC=2059;AMQ9643:
 Remote SSL peer name error for channel 'ABC.XYZ'
        at com.ibm.mq.jmqi.remote.internal.system.RemoteConnection.
analyseErrorSegment(RemoteConnection.java:4607)
        at com.ibm.mq.jmqi.remote.internal.system.RemoteConnection.
receiveTSH(RemoteConnection.java:3086)
        at com.ibm.mq.jmqi.remote.internal.system.RemoteConnection.
initSess(RemoteConnection.java:1532)
        at com.ibm.mq.jmqi.remote.internal.system.RemoteConnection.
connect(RemoteConnection.java:1201)
        at com.ibm.mq.jmqi.remote.internal.system.RemoteConnectionPool.
getConnection(RemoteConnectionPool.java:354)
        at com.ibm.mq.jmqi.remote.internal.RemoteFAP.
jmqiConnect(RemoteFAP.java:1662) 

You can also use the wild card while adding SSL Peer on the server-side e.g. following wild card will allow any client which has TEST_CERTS in its common name.

SSLPEER(CN=TEST_CERTS*)


That's all about SSL related errors from WebSphere MQ, also known as WMQ. It takes a lot of time to troubleshoot and solve this error, especially if you don't understand how SSL,Certificate and Java works together. WMQ is also a niche technology so its expected that many Java programmer is not familiar with how it works and other setup related stuff which is mostly handled by middleware team. Communicating with them could be a real pain if you couldn't explain the right cause to them. Its better to befriend them so that you can work together while troubleshooting a MQ SSL related issue.


If you like this tutorial and looking for more stuff on IBM WMQ, then don't forget to check out my other Java tutorial related to MQ, SSL,Messaging, Tibco and Java :

• 10 WebSphere MQ Interview Questions for Java developers (list)
• What is difference between Web and Application Server? (answer)
• Difference between Tibco EMS and Tibco RV? (answer)
• How Tibco RV messaging works? (explanation)
• 10 Tibco Rendezvous Tips and Commands? (tips)