Friday, March 31, 2017

Failed to connect to queue manager - WebSphere MQ Error in Java

"Failed to connect to queue manager" error comes in WebSphere MQ if any Client e.g. Java program is not able to connect to 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 server due to unknown or expired SSL certificates. If you are working in Java application which 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 nightmare, forget about solving them. I have gone through that and after spending hours on Google and Websphere MQ documentations, 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 looked at three errors :
  • Unable to find valid certification path to requested target
  • JMSWMQ2020: Failed to connect to 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 system 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 expiry of SSL certificates which our Java client is using to connect to MQ series. Here is the exact exception :

Error :
SSL handshake failed. [[ PKIX path building failed: 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 keystore. Also add new signer certificates into trust store which is used by server. This would be required during SSL handshake. Once we updated our our Java application's truststore and keystore this error was solve. It took me long time to understand and fix this error because I wasn't aware of exact difference between keystore and truststore and how exactly they are used during SSL handshake process.

WebSphere MQ SSL Errors and Solution

JMSWMQ2020: Failed to connect to queue manager

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

Error JMSWMQ2020: Failed to connect to queue manager
Caused by: JMSCMQ0001: WebSphere MQ call failed with compcode '2' ('MQCC_FAILED') reason '2397' ('MQRC_JSSE_ERROR').

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

Solution:  Once we added new set of SSL certificate 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 MQ client and server has correct set of certificates, and you are still not able to connect other, then there could be an issue with SSL Peer setup. Common name, ("cn" field in your SSL certificate) of client's personal SSL certificates are required to be added as SSLPEER on server side, and if that's not setup, SSL connection will not establish and MQ will give you following error :

Caused by: JMSCMQ0001: WebSphere MQ call failed with compcode '2' ('MQCC_FAILED') reason '2059' ('MQRC_Q_MGR_NOT_AVAILABLE').
Caused by: CC=2;RC=2059;AMQ9643: Remote SSL peer name error for channel 'ABC.XYZ'

You can check here MQ code for reason is 2059, which is different than previous code 2397. So paying a close attention on 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 common name (CN) from client applications personal certificates e.g. for following common name :

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

SSLPeer entry should be :


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: JMSCMQ0001: WebSphere MQ call failed with compcode '2' ('MQCC_FAILED') reason '2059' ('MQRC_Q_MGR_NOT_AVAILABLE').


Caused by: CC=2;RC=2059;AMQ9643: Remote SSL peer name error for channel 'ABC.XYZ'

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


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

Further Learning
Understanding the Java Virtual Machine: Security
Understanding and Solving Java Memory Problems
Java Performance The Definitive Guide By Scott Oaks

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)


Anonymous said...

Hi Javin,

Thanks for the post. I am new to work for Websphere MQ. Can you suggest me for some good MQ tutorial. I can google it but can't find any good tutorial.or can you write for us?


Javin Paul said...

@Anonymous, You are right, there are lack of good MQ Series tutorial. All I had did was to read some documentation from WebSphere available. I'll try to write some basic one for sure.

Post a Comment