How to Fix the “Remote Host Terminated the Handshake” Error
“Remote host terminated the handshake” means the other end of the connection closed it before SSL/TLS negotiation finished, often because of incompatible TLS settings, a certificate requirement, or a proxy or network policy. In Java, it commonly appears as javax.net.ssl.SSLHandshakeException, but that exception alone does not identify the cause. Match the surrounding evidence to the likely problem before changing certificates or security settings.
| Symptom or Additional Evidence | Likely Cause | Targeted Fix |
|---|---|---|
| Connection closes without a useful TLS alert | Wrong listener, missing SNI, proxy rejection, or source-IP restriction | Verify the destination and inspect gateway or server logs |
TLS alert such as protocol_version |
No acceptable protocol overlap | Align the client and server’s supported TLS configuration |
handshake_failure alert |
Cipher, signature algorithm, client-certificate, or another negotiation mismatch | Inspect the handshake trace and server-side rejection reason |
PKIX path building failed |
Missing intermediate certificate or an untrusted certificate authority | Repair the server chain or the application’s truststore |
| Server requests a client certificate, but none is accepted | Missing or unsuitable mutual-TLS credentials | Configure the client’s private key and certificate chain |
| Failure occurs only in one container, service, or runtime | Different truststore, proxy, runtime, or enabled TLS settings | Compare the failing process’s actual configuration |
| Failure occurs during deployment or node shutdown | Requests reaching a departing or unavailable endpoint | Check connection draining, service discovery, and node lifecycle |
What the Handshake Error Means
A TLS handshake establishes the encrypted connection and authenticates the server. Depending on the service, it may also authenticate the client through mutual TLS, or mTLS.
A typical Java exception looks like this:
javax.net.ssl.SSLHandshakeException: Remote host terminated the handshake
Caused by: java.io.EOFException: SSL peer shut down incorrectly
The EOFException means Java encountered an unexpected end to the connection. It is a symptom, not proof that a certificate is expired or that the server needs a different TLS version.
The “remote host” might be the application server, but it could also be a reverse proxy, load balancer, API gateway, or TLS-inspection device. That distinction determines whose logs and configuration matter.
For HTTPS, this failure happens before an HTTP exchange can complete on that connection. Changing an API token or request body usually will not solve it. An HTTP authentication error, by contrast, means the connection progressed far enough to receive an HTTP response.
How to Fix Remote Host Handshake Termination
Work through these checks in order. Apply a repair only when the evidence supports it; installing certificates and changing protocols indiscriminately can hide the original problem.
Step 1: Identify the Failing Endpoint and Runtime
- Record the complete exception chain along with the surrounding log messages, timestamp and time zone, destination hostname and port, and failed operation. A TLS alert immediately before the exception is more useful than the final stack-trace line.
- Identify the process making the connection. For a containerized application, inspect the running container, not just the host. For an agent or scheduled service, check its configured Java executable and startup options. To inspect the Java executable selected by your current shell, run:
java -versionCheck the service’s launch configuration before treating the output as its runtime version.
- Identify the actual failing destination. Authentication, redirects, deployment downloads, and artifact retrieval may use different hosts. A successful request to the main service does not validate a subsequent connection to another endpoint.
Also note recent changes: certificate renewal, proxy replacement, container-image updates, runtime updates, or a deployment. These help narrow the investigation without assuming that the most recent change must be responsible.
Step 2: Reproduce the TLS Connection From the Failing Environment
- Reproduce the TLS failure from the affected host or container where possible so the test uses the failing environment’s network context. A laptop test may use different DNS, trusted CAs, proxies, and outbound addresses.
- Inspect the endpoint with OpenSSL. Replace
api.example.comand the port with the actual destination:openssl s_client -connect api.example.com:443 -servername api.example.com -showcerts -verify_return_error -verify_hostname api.example.comThe
-servernameoption sends Server Name Indication, or SNI, so a shared TLS listener can select the intended virtual host. The verification options make certificate and hostname failures visible rather than treating an encrypted connection alone as success. Stop the diagnostic connection with Ctrl+C after reviewing the output. Plains_clientdoes not automatically reproduce an application’s HTTP proxy configuration. If the application uses a proxy, test that approved route as well; a direct connection is not an equivalent test. - Determine how far the handshake gets. – If TCP cannot connect, investigate name resolution, routing, the listener, or network access. – If the peer closes before presenting a certificate, focus on the listener, SNI, TLS negotiation, and gateway policy. – If the server presents a certificate and verification fails, investigate identity and trust. – If the server requests a client certificate, investigate mTLS.
OpenSSL and Java can use different truststores and TLS implementations. An OpenSSL success narrows the problem without confirming that the Java application is configured correctly.
For a Java-only failure, temporarily enable TLS handshake diagnostics through the application’s supported JVM startup configuration. Capture a controlled reproduction and look for the last handshake message, any received alert, and the peer’s certificate request. Protect these logs because they can expose internal hostnames and certificate details.
Step 3: Correct the Destination, Proxy, and Network Policy
- Confirm that the port expects the connection you are making. A TCP connection can succeed even when the listener expects plaintext or a protocol-specific upgrade rather than immediate TLS.
- Check the route and observed source address. Behind NAT, a proxy, or cloud egress infrastructure, the remote service may see a different IP address from the machine’s local address. If the destination uses an allowlist, have its administrator confirm the address actually seen in the logs.
- Match gateway logs to the failed attempt. Look for rejected SNI names, TLS-policy failures, source restrictions, or an unavailable upstream. Correct only the relevant listener, routing, or access rule, then repeat the failing application operation.
Do not assume the first corrected problem is the only one. Removing an IP restriction can allow negotiation to proceed far enough to expose a separate certificate-trust error.
Avoid disabling the firewall or bypassing an organizational proxy as a general repair. Those changes can alter the connection path without fixing the application’s intended configuration.
Step 4: Resolve TLS Protocol and Cipher Incompatibility
- Check which TLS protocols the application and security policy actually enable, rather than relying on the runtime’s list of supported protocols. Compare the client’s actual handshake offer with the server listener’s accepted configuration.
- Test protocol negotiation when the evidence points to compatibility. To test TLS 1.2 against the endpoint:
openssl s_client -connect api.example.com:443 -servername api.example.com -tls1_2 -verify_return_error -verify_hostname api.example.comTo test TLS 1.3:
openssl s_client -connect api.example.com:443 -servername api.example.com -tls1_3 -verify_return_error -verify_hostname api.example.comThese commands require an OpenSSL build that supports the requested protocol. An unrecognized option is a local-tool limitation, not a rejection by the remote server.
- Repair the incompatible component. Prefer an updated, product-supported runtime or TLS library. If the application explicitly restricts protocols or cipher suites, adjust that configuration to match the endpoint’s approved policy. If both sides support the same protocol but negotiation still fails, compare cipher suites, signature algorithms, and the server’s rejection logs.
After the change, restart or redeploy the affected application when required and retry its original operation. A successful forced-protocol test does not prove that the application now offers the same protocol and algorithms.
Do not enable obsolete protocols or weak ciphers merely to suppress the exception.
Step 5: Repair Server Identity and Certificate Trust
Certificate repair is appropriate when verification errors or handshake logs point to the server’s certificate.
- Check the certificate itself. Confirm that it is valid for the requested hostname, is within its validity period, and is being evaluated against a correct system clock. Correct a bad clock through the system’s normal time-synchronization mechanism; renew or replace an unsuitable certificate.
- Check the chain served by the endpoint. The TLS listener generally needs to present its leaf certificate and the necessary intermediate certificates. It normally does not need to send the root certificate. OpenSSL’s
-showcertsoutput shows what the server sent, not necessarily a complete, trusted chain. If an intermediate is missing, install the corrected chain on the TLS-terminating server or proxy, reload it through its supported process, and test the application again. - Check the truststore used by the failing process. Java may use a bundled truststore, an application-specific store, or a custom SSL context rather than the operating system’s CA store. For an approved private CA, obtain its certificate through a trusted administrative channel. Back up the existing application truststore before changing it. For an existing PKCS12 truststore, an import can look like this; replace the filenames and use an appropriate, unused alias:
keytool -importcert -alias organization-root-ca -file organization-root-ca.pem -keystore app-truststore.p12 -storetype PKCS12Let
keytoolprompt for the password. Accept the import only after verifying the CA certificate’s fingerprint through a trusted channel. Do not create an empty replacement truststore unintentionally or import a downloaded certificate solely because it makes the error disappear. - Reload the application’s trust configuration and retest. Restart the affected process if it loads trust material only at startup. Confirm that the original request now succeeds with certificate and hostname verification enabled.
A browser’s successful connection is not enough to rule out trust problems: browsers and Java applications can build certificate chains differently and trust different authorities.
Step 6: Supply the Client Certificate When mTLS Is Required
A truststore answers, “Which remote certificates should this client trust?” A client keystore answers, “Which certificate and private key can this client present?” Importing the server’s CA certificate does not supply a client identity.
- Check the server configuration or handshake trace for a client-certificate requirement before configuring an mTLS identity. Do not add client-certificate settings to a service that does not request them.
- Inspect the configured client keystore. For a PKCS12 file:
keytool -list -v -keystore app-client.p12 -storetype PKCS12The intended identity must have a
PrivateKeyEntry, not merely atrustedCertEntry. Check its validity, certificate chain, and suitability for client authentication. - Build or obtain the correct identity bundle. If you already have the authorized client certificate, its matching private key, and intermediate certificates, OpenSSL can package them:
openssl pkcs12 -export -in client-cert.pem -inkey client-key.pem -certfile client-intermediates.pem -out app-client.p12Enter an export password when prompted. Protect both the private-key file and the resulting bundle.
- Configure the connection to use that identity. Set the application’s client keystore, store type, credentials, and certificate alias where applicable. In integration platforms, uploading a keystore may not automatically bind it to an outbound connection. Reload the configuration, retry the original operation, and confirm in the server logs that the intended client certificate was presented and accepted.
Handshake Failures in Different Environments
The same handshake exception can indicate incompatible TLS settings or traffic reaching a departing endpoint, so check the destination and its lifecycle before changing cryptographic settings.
Deployments and Cluster Communication
During rolling deployments, a peer can stop accepting connections while other nodes still have references to it.
In Keycloak, JGRP000034 handshake errors associated with messages sent to a departing cluster node can be harmless stale inter-node traffic. That does not make every handshake error during a deployment harmless.
Correlate the message with node departure, cluster membership, readiness, and actual request failures. If errors stop when the old node leaves and user-facing requests remain healthy, certificate replacement may be unnecessary. Persistent failures between active nodes need a separate TLS and connectivity investigation.
Download Clients and Managed Integrations
With AWS Greengrass, a working MQTT connection does not validate the HTTPS connection used to download deployment material. Those paths may involve different endpoints, policies, and trust configuration.
Likewise, an integration platform such as IFS can have separate controls for outbound routing, trusted server certificates, and client identities. Check which outbound connection actually uses the uploaded keystore.
The error can also appear when launching a shared Minecraft modpack. Identify the failing remote address and the launcher’s selected runtime before changing modpack files; the exception by itself does not establish that a mod is defective.
Mail Services and STARTTLS
Some mail listeners begin with a plaintext protocol exchange and upgrade to TLS through STARTTLS. Sending an immediate TLS handshake to such a listener tests the wrong connection behavior.
For an SMTP listener configured to offer STARTTLS on port 25:
openssl s_client -connect mail.example.com:25 -starttls smtp -servername mail.example.com -showcerts -verify_return_error -verify_hostname mail.example.com
Replace the hostname with the actual mail server. If this succeeds while an immediate-TLS test fails, configure the mail client for the listener’s intended STARTTLS mode and retry the original mail operation. Success on a server’s HTTPS web interface does not validate its SMTP, IMAP, or POP listeners.
How to Confirm the Fix and Prevent a Repeat
Confirm the repair through the application, not just a diagnostic utility:
- The original request, download, job, or integration completes.
- Certificate-chain and hostname verification remain enabled.
- Required client authentication presents the intended identity.
- Server or gateway logs no longer show the corresponding rejection.
- The connection still works after the application restarts or redeploys.
If the problem was intermittent, compare successful and failed attempts by destination address, backend instance, proxy route, and deployment state. A single successful test can miss an inconsistently configured load-balancer backend.
Remove temporary TLS debug logging after collecting the necessary evidence. Keep runtime and base-image updates controlled, monitor certificate expiration, and document which component owns server trust, client identity, and outbound proxy configuration.
If the operation still fails, send the endpoint owner a compact diagnostic bundle: the timestamp and time zone, destination hostname and port, observed outbound address, runtime version, complete exception chain, and sanitized handshake output. Exclude private keys, passwords, tokens, and presigned URL query strings.
Frequently Asked Questions
How Do I Fix a LogicMonitor Collector SSL Handshake Failure?
Diagnose the connection from the Collector host and the Collector’s actual runtime, not from the browser used to access the monitoring console. Identify whether the failure affects an outbound service connection or a monitored endpoint, because they can use different proxy and certificate settings. Apply the supported runtime, trust, or connection correction to the affected Collector and rerun the failed collection or connection test.
How Do I Fix “Remote Host Terminated the Handshake” in a Salesforce Apex Callout?
For an Apex callout, investigate the destination’s TLS listener, certificate chain, network restrictions, and any required client certificate. You cannot fix Salesforce’s managed runtime by adding local JVM options, so correlate the callout timestamp with the destination’s server or gateway logs. Correct the endpoint or the callout’s authentication configuration, then repeat a controlled callout.
What Should I Check When This Error Appears in a Redwood System?
Start with the worker, agent, or service that actually opens the remote connection, not the browser displaying the job error. Inspect the failed job’s destination and that component’s runtime, proxy, truststore, and client-certificate configuration. Apply the correction to the executing component, reload it when required, and rerun the job safely, accounting for any work the earlier attempt already completed.
