IBM Support

IBM MQ connection failing after upgrading application to Java 17 or above — SSL handshake fails while connecting

Troubleshooting


Problem

After upgrading an application from an older Java version to Java 17, the application may fail to establish an MQ connection to IBM Sterling Order Management, even when a valid certificate is in use. The connection fails during the SSL/TLS handshake stage, and the issue may persist even after regenerating the keystore/truststore and confirming the certificate validity.

 

Symptom

Applications may encounter the following error when attempting to connect or receive messages from a queue:

org.springframework.jms.UncategorizedJmsException: Uncategorized exception occurred during JMS processing; nested exception is com.ibm.mq.MQException: JMSCMQ0001: IBM MQ call failed with compcode '2' ('MQCC_FAILED') reason '2397' ('MQRC_JSSE_ERROR').

 

This may also appear alongside:

com.ibm.mq.jmqi.JmqiException: CC=2;RC=2397;AMQ9204: Connection to host '()' rejected.
[1=com.ibm.mq.jmqi.JmqiException[CC=2;RC=2397;AMQ9771: SSL handshake failed.
[1=java.net.SocketException[Connection reset], ... 5=RemoteTCPConnection.protocolConnect]

 

Key observations:

The connection is dropped during the SSL handshake itself, before a full response is received from the MQ server.
The certificate chain, validity dates, and keystore/truststore configuration are all confirmed valid.
The issue is reproducible only on applications that have been upgraded to Java 17 or next.

 

Cause

Moving to Java 17 typically requires migrating from the legacy javax messaging libraries to the newer jakarta libraries, which in turn requires upgrading the IBM MQ client library to a newer version.

Newer IBM MQ client versions (from 9.2.1 onwards) introduce an additional required configuration property that governs how the client presents the target hostname during the SSL/TLS handshake (Server Name Indication). If this property is not set, the MQ server may be unable to correctly route the incoming SSL connection to the appropriate queue manager, and it terminates the connection rather than completing the handshake. This produces the JSSE/SSL-related error above, even though the certificate itself is valid and unexpired.

Related contributing factors to verify:

  • Mismatch between the MQ Client jar version and the MQ Server version.
  • Cipher suite compatibility with Java 17.

  • Missing mandatory Jackson libraries (jackson-annotations, jackson-core, jackson-databind), required from IBM MQ 9.3.3 onwards for TLS connections.

     

Diagnosing The Problem

  • Confirm the Java version in use by "java -version".
  • Confirm the IBM MQ client (ibm.mq.allclient) jar version and compare it against the MQ Server version — these should match.
  • Review the MQ connection configuration and confirm which SSL/TLS-related system properties are currently set (e.g., com.ibm.mq.cfg.useIBMCipherMappings).
  • Validate the keystore and truststore using:

keytool -list -v -keystore <your-keystore.jks>

 

  • Confirm keystore type, alias name, validity dates, and certificate chain.
  • Confirm the cipher suite in use is supported for the Java and MQ client versions involved.

  • Confirm required Jackson dependencies are present in the application classpath.

     

Resolving The Problem

  • Add the following system property to the client application configuration, alongside any existing MQ-related properties:

-Dcom.ibm.mq.cfg.SSL.outboundSNI=Hostname 

 

Document Location

Worldwide

[{"Type":"MASTER","Line of Business":{"code":"LOB77","label":"Automation Platform"},"Business Unit":{"code":"BU048","label":"IBM Software"},"Product":{"code":"SSGTJF","label":"IBM Sterling Order Management System"},"ARM Category":[{"code":"a8m0z000000cxzcAAA","label":"Services and MQ"}],"ARM Case Number":"","Platform":[{"code":"PF025","label":"Platform Independent"}],"Version":""}]

Document Information

Modified date:
27 July 2026

UID

ibm17280956

Page Feedback