How To Fix Failed To Connect To Queue Manager - WebSphere MQ ...

Có thể bạn quan tâm

Javarevisited

Learn Java, Programming, Spring, Hibernate throw tutorials, examples, and interview questions

Wednesday, March 19, 2025

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. WebSphere MQ SSL Errors and Solution

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,Certificates 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)

By javin paul at March 19, 2025

Labels: error and exception , MQ Series , troubleshooting

3 comments :

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?Thanks,

April 13, 2015 at 6:35 AM

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.

April 13, 2015 at 7:13 AM

Anonymous said...

Hi Javin,I can't tell you how much helpful this post has been, especially SSL Peer Failure Issue. We struggled for weeks. Thanks a lot for this post. Vivek Mishra

December 17, 2019 at 2:42 PM

Best System Design and Coding Interview Resources

System Design & Interview Prep

ByteByteGo Lifetime Plan (50% OFF)
Codemia Lifetime Plan (60% OFF)
Exponent Annual Plan (70% OFF)
Educative Premium Plus (55% OFF)
DesignGurus All Course Bundle (55% OFF)
Everything Java Interview Bundle (50% OFF)
101 Blockchain (50% OFF)
Vlad Mihalcea's High Performance Bundle (50% OFF)
Javarevisited Substack Subscription (50% OFF)
Head First Software Architecture (Book)

Best Online Learning Resources and Platforms

Coursera Plus Discount (40% OFF)
Datacamp Discount (50% OFF)
AlgoMonster Discount (50% OFF)
Udemy Discount (80% OFF)
Baeldung Discount (33% OFF)
LabEx Discount (50% OFF)
Codecademy Discount (50% OFF)
Udacity Discount (50% OFF)
ZTM Academy Discount (20% OFF)
Frontend Masters Discount (10% OFF)
Whizlabs Discount (30% OFF)

Search This Blog

Preparing for Java and Spring Boot Interview?

Join My Newsletter .. Its FREE

My Books

Everything Bundle (Java + Spring Boot + SQL Interview) for a discount
Grokking the Java Interview
Grokking the Spring Boot Interview
Spring Framework Practice Questions
Grokking the SQL Interview
Grokking the Java Interview Part 2
Grokking the Java SE 17 Developer Certification (1Z0-829 Exam)

My Courses

Spring Professional Certification Practice Test
Java SE 11 Certification Practice Test
Azure Fundamentals AZ-900 Practice Test
Java EE Developer Exam Practice Test
Java Foundations 1Z0-811 Exam Practice Test
AWS Cloud Practitioner CLF-C02 Exam Practice Test
Java SE 17 1Z0-829 Exam Practice Test
Azure AI-900 Exam Practice Test
1Z0-829 Java Certification Topic wise Practice Test

My Newsletter articles

How to grow financially as Software Engineer?
Difference between Microservices and Monolithic Architecture
What is Rate Limiter? How does it work
Difference between @Component vs @Bean annotations in Spring Framework?
Top 10 Software Design Concepts Every Developer should know
How does SSO Single Sign On Authentication Works?

Interview Questions

core java interview question (183)
interview questions (113)
data structure and algorithm (99)
Coding Interview Question (88)
spring interview questions (52)
design patterns (48)
object oriented programming (42)
SQL Interview Questions (37)
thread interview questions (30)
collections interview questions (26)
database interview questions (16)
servlet interview questions (15)
hibernate interview questions (11)
Programming interview question (6)

Java Tutorials

FIX protocol tutorial (16)
JDBC (35)
Java Certification OCPJP SCJP (33)
Java JSON tutorial (23)
Java Programming Tutorials (21)
Java multithreading Tutorials (64)
Java xml tutorial (16)
date and time tutorial (27)
java IO tutorial (30)
java collection tutorial (94)
jsp-servlet (37)
online resources (227)

Get New Blog Posts on Your Email

Get new posts by email:

Followers

Blog Archive

► 2026 (71)
- ► February (35)
- ► January (36)

▼ 2025 (910)
- ► December (23)
- ► November (33)
- ► October (121)
- ► September (39)
- ► August (20)
- ► July (111)
- ► June (106)
- ► May (85)
- ► April (116)
- ▼ March (32)
  - Which Programming Books Would You Buy If you got 1...
  - 3 Books to Learn Eclipse IDE for Java JEE Programm...
  - Top 2 Books for OCPJP8 Certification - Java 8 1Z0-...
  - Top 5 Java And Android Game Programming Books for ...
  - Top 5 Free Scala Programming Books for Java Progra...
  - How to Enroll on Spring Professional Certification...
  - Why become a Certified Java Programmer? Does Oracl...
  - How to share your Programming Articles on Javarevi...
  - How I lost 10 Kg weight by Buying A Digital Weight...
  - How to sort array in decreasing order in Java? Exa...
  - FIX Session is not connecting how to diagnose it? ...
  - How to Fix java.sql.SQLException: No suitable driv...
  - How to Fix Failed to connect to queue manager - We...
  - How to fix java.net.SocketException: Too many file...
  - 3 Ways to Solve jQuery - Uncaught ReferenceError: ...
  - Top 5 Udemy Courses to Learn VI Editor or Vim in L...
  - Top 5 Udemy + Coursera Courses to Learn Computer V...
  - Top 5 Udemy Courses to Learn GraphQL for Beginners...
  - Top 5 Udemy Courses to Crack CompTIA Linux+ Certif...
  - Top 5 Udemy + Pluralsight Courses to Learn Vue.js ...
  - Top 6 Udemy Courses and Books to learn Rust Progra...
  - Top 5 Udemy Courses to Learn Groovy and Grails Onl...
  - Top 5 Udemy Courses and Books to Learn Gradle for ...
  - Top 5 Udemy Courses to learn Scala Programming Onl...
  - Top 5 Udemy Courses to Learn RedHat OpenShift in 2...
  - Top 5 Courses to Learn Microsoft SQL Server Databa...
  - Top 5 Postman Courses for Java Web Developers and ...
  - Top 3 Udemy Courses to Learn Svelte.js in 2025 - B...
  - Top 5 Udemy Courses to learn Unreal Engine in 2025...
  - Top 10 Free Courses to Learn Angular and React.js ...
  - Top 5 Udemy Courses to Learn C# in 2025 - Best of Lot
  - Top 6 Udemy Courses to Learn TypeScript for Web De...
- ► February (105)
- ► January (119)

► 2024 (185)
- ► December (14)
- ► November (3)
- ► October (35)
- ► September (28)
- ► August (10)
- ► July (20)
- ► June (7)
- ► May (24)
- ► April (30)
- ► March (9)
- ► February (1)
- ► January (4)

► 2023 (511)
- ► December (4)
- ► November (4)
- ► October (7)
- ► September (149)
- ► August (20)
- ► July (43)
- ► June (2)
- ► May (151)
- ► April (91)
- ► March (27)
- ► February (8)
- ► January (5)

► 2022 (69)
- ► December (1)
- ► September (1)
- ► August (20)
- ► July (20)
- ► June (7)
- ► May (5)
- ► April (4)
- ► March (3)
- ► February (6)
- ► January (2)