MQRC 2397: JSSE error

What it means

Java applications using the IBM MQ classes for Java or JMS do TLS through the JVM's JSSE provider, not through MQ's own TLS code. When JSSE throws an exception, MQ wraps it in an MQException with reason 2397 and completion code MQCC_FAILED. In JMS, that MQException is linked to the JMSException the application sees. The reason code only applies to Java.

2397 says where the problem is, not what it is. You get the detail from the cause chain, with getCause() on the MQException or getLinkedException() on the JMSException. Typical causes are a handshake failure because the server's certificate isn't trusted, the keystore or truststore not being found or opened, a protocol or cipher suite that one side doesn't allow, or a client certificate the queue manager requires but the client doesn't send.

Cipher suites cause many 2397 errors. MQ channels name a CipherSpec, and Java names a cipher suite, and the two must match. On a non-IBM JRE, MQ's mapping between the names depends on the com.ibm.mq.cfg.useIBMCipherMappings system property, which should be false on Oracle and OpenJDK JREs.

Common causes

• The server certificate isn't trusted because the truststore lacks the issuing CA. The cause chain often shows a certificate path error.
• The keystore or truststore can't be found or opened, for example a wrong javax.net.ssl.keyStore path or password.
• The cipher suite set on the client doesn't match the SSLCIPH CipherSpec on the server-connection channel, or the JRE doesn't enable it.
• On an Oracle or OpenJDK JRE, IBM cipher name mappings are still on, so MQ can't map the cipher suite correctly.
• The channel requires a client certificate (SSLCAUTH(REQUIRED)) and the client keystore has none, or not the expected one.

How to find the problem

1. Print the whole exception chain. Use getCause() on the MQException, or getLinkedException() on the JMSException, and read the innermost JSSE exception.
2. Turn on JSSE tracing with the JVM option -Djavax.net.debug=ssl:handshake to see which keystore and truststore load and where the handshake stops.
3. Check the channel with DISPLAY CHANNEL(APP.TLS.SVRCONN) SSLCIPH SSLCAUTH and compare with the client's cipher suite.
4. Read the queue manager error log at the same time. It often names the TLS problem from the server's side.

How to fix it

• Import the CA certificate that signed the queue manager's certificate into the client truststore.
• Set the keystore and truststore paths and passwords correctly, through javax.net.ssl.* system properties or the application server's TLS settings.
• Use a cipher suite that matches the channel's CipherSpec, and set -Dcom.ibm.mq.cfg.useIBMCipherMappings=false on non-IBM JREs.
• If the channel requires client authentication, add a personal certificate to the client keystore and make sure the queue manager trusts its issuer.

What it looks like

JMSCMQ0001: IBM MQ call failed with compcode '2' ('MQCC_FAILED') reason '2397' ('MQRC_JSSE_ERROR').

Technical reviewer: Albert Joseph, WND Software.

Last reviewed 2026-10-18 by the WND Software team. Written in our own words. For the full reference, check IBM’s MQ documentation for your version.