Mirth Connect SSL Handshake Failure: Causes and Fix

A Mirth Connect SSL handshake failure appears in the server log as javax.net.ssl.SSLHandshakeException, often followed by a more specific cause like PKIX path building failed for a certificate problem or a protocol mismatch message for a version conflict. The connection never completes, so no message data is exchanged until the underlying trust or protocol issue is resolved.

Below is what actually breaks the handshake, the fix for each cause, and how to stop it recurring after a renewal. Our free Mirth Health Check can confirm which side of the handshake is rejecting the connection — part of the Mirth Connect support work we do for US healthcare teams.

An SSL handshake fails when the client and server can't agree on trust, protocol version, or cipher suite before any data is exchanged. Mirth can be on either side of that handshake depending on the connector, so the fix differs slightly whether Mirth is connecting out to a destination or accepting an inbound connection from a sender. Identifying which role Mirth plays in the failing connection is the first useful step, since the four causes below apply a little differently depending on that direction.

Untrusted or Self-Signed Certificate in the Truststore

If the certificate presented by the other side isn't signed by a certificate authority Mirth's truststore recognizes, the handshake fails immediately with a path-building error. Self-signed certificates and internal CAs are the most common source on internal healthcare networks.

Expired Certificate on Either End of the Connection

A certificate that has passed its expiration date fails validation regardless of whether it was trusted before, and the error message doesn't always make the expiration obvious. This is common right after a renewal is missed.

Mismatched TLS Protocol Version Between Client and Server

If one side only supports TLS 1.2 and the other has been hardened to require TLS 1.3, or vice versa, the handshake fails before certificates are even exchanged. Recent security hardening on either endpoint commonly triggers this specific failure.

Cipher Suite Not Supported by Both Sides

Even with matching protocol versions and valid certificates, a handshake can still fail if neither side offers a cipher suite the other accepts. This is less common than the other causes but shows up after a JVM or OpenSSL upgrade.

Confirm which of the four causes above applies by reading the specific exception text in the server log rather than assuming it's always a certificate problem, since the fix for a protocol mismatch is entirely different from a trust issue. The fixes below are ordered from the most common cause to the least common, so work through them in that order unless the log already points you toward something specific right away.

Import the Certificate Into Mirth's Truststore

Use keytool -importcertto add the other endpoint's certificate, or its issuing CA, into the truststore Mirth's JVM is configured to use. Restart the service afterward, since the truststore is loaded once at startup, not per connection.

Renew or Replace the Expired Certificate

Generate or obtain a renewed certificate for whichever endpoint has expired, and update the corresponding keystore or truststore entry to match. Confirm the new certificate's validity dates before deploying it to avoid repeating the same failure shortly after.

Align Supported TLS Versions on the Connector

Check the connector's SSL configuration for an explicit protocol setting, and adjust it so both endpoints support at least one common TLS version. Where possible, standardize on the newer supported version rather than downgrading for compatibility.

Update the Cipher Suite Configuration

If the protocol versions already match, review the cipher suites enabled on the connector and compare them against what the other endpoint supports. Add or enable a mutually supported suite rather than disabling security features broadly to work around it.

Most handshake failures are entirely predictable well in advance, since certificates have known expiration dates and protocol requirements rarely change without a deliberate hardening effort on one side. Treating certificate and protocol management as routine maintenance, rather than something addressed only after a connection breaks in production, prevents almost every recurrence of this specific error across every integration your Mirth instance depends on.

Track Certificate Expiration Dates

Keep a simple log of every certificate Mirth depends on, along with its expiration date, and review it well ahead of any renewal deadline. This alone prevents the single most common cause of sudden, unexplained handshake failures.

Test SSL Changes in Staging First

Any change to a certificate, truststore, or protocol setting should be tested against a staging instance before it reaches production, since a mismatch discovered there costs minutes instead of a production outage.

Keep Truststores Synced Across Environments

A certificate trusted in staging but never added to production's truststore is a common gap that only surfaces once the channel is promoted. Syncing truststore contents as part of your deployment process closes this gap.

Document Which Protocol Version Each Endpoint Requires

Recording the minimum TLS version each integration partner requires, and reviewing it whenever either side changes its security posture, prevents a hardening change from silently breaking a connection you didn't know was affected.

If you've confirmed the certificate is trusted and current and the handshake still fails, the cause is usually a protocol or cipher mismatch that's easy to miss without comparing both endpoints' SSL configuration side by side. Our free Mirth Connect health check confirms which side is rejecting the connection as part of the standard diagnostic.

Book a Free Health Check →

Have the exact exception text? Send us the log, or check pricing for ongoing support plans.