Java: Remote host closed connection during handshake
You deploy a Java service, it works in staging, and in production every call to a partner API dies with the same stack trace:
javax.net.ssl.SSLHandshakeException: Remote host closed connection during handshake
at sun.security.ssl.SSLSocketImpl.readRecord(SSLSocketImpl.java:983)
at sun.security.ssl.SSLSocketImpl.performInitialHandshake(SSLSocketImpl.java:1385)
Caused by: java.io.EOFException: SSL peer shut down incorrectly
This is one of the least informative TLS errors Java produces, because it tells you that the handshake died but not why. The sections below show how to turn that into a specific answer in a few minutes, with commands you can paste into a terminal.
What “Remote host closed connection during handshake” actually means
The TCP connection was established successfully — so DNS resolution, routing and the firewall are fine. The peer (or something sitting in the path) then closed the socket after receiving the ClientHello, before the handshake completed, and without sending a TLS alert. That missing alert is why the JDK reports an EOFException wrapped in an SSLHandshakeException instead of a clean Received fatal alert: ... message.
In practice the cause is one of four things:
- Protocol version mismatch. The client offers only TLS 1.0/1.1 (old JDK defaults, or a hardened
java.security) while the server accepts only TLS 1.2/1.3. Many load balancers and CDNs silently drop the connection rather than replying withprotocol_version. - Cipher suite mismatch. No overlap between client and server suites — common after a server disables CBC, 3DES or RC4 while the client is an old JDK build.
- SNI missing or wrong. The client connects by IP address, or an ancient JRE has SNI disabled, so the front end has no matching virtual host and closes the socket.
- A middlebox. A TLS-inspecting corporate proxy, an IPS/IDS that resets connections based on SNI or record size, or a load balancer whose backend pool is configured differently from its front end.
Note what it is not: it is almost never a certificate or trust-store problem. Trust failures happen later in the handshake and surface as PKIX path building failed or unable to find valid certification path to requested target.
Step 1 — Turn on JSSE handshake logging
Java’s built-in TLS debug output tells you exactly which message was the last one sent or received. Add the flag to the JVM that actually fails — the container, the app server node, the CI runner — not your laptop:
java -Djavax.net.debug=ssl:handshake -jar app.jar 2>&1 | tee handshake.log
Useful variants:
ssl:handshake— handshake messages only. The right default; output is large but readable.ssl:handshake:verbose— adds a full record dump, including the ClientHello extensions (SNI,supported_versions,signature_algorithms). Use this when you need to prove what your client actually offered.ssl— everything (sessions, ciphers, records). Noisy; only for deep debugging.
In a servlet container, add it to the startup options instead: export CATALINA_OPTS="$CATALINA_OPTS -Djavax.net.debug=ssl:handshake". Then narrow the output:
grep -nE 'ClientHello|ServerHello|alert|Exception|EOF' handshake.log
If you cannot change JVM flags, enable it programmatically before any SSL class is initialized:
System.setProperty("javax.net.debug", "ssl:handshake");
Step 2 — Read the log: where exactly did it die?
A classic failure looks like this — the ClientHello goes out, then nothing comes back:
main, WRITE: TLSv1.2 Handshake, length = 210
main, received EOFException: error
main, handling exception: javax.net.ssl.SSLHandshakeException: Remote host closed connection during handshake
main, SEND TLSv1.2 ALERT: fatal, description = handshake_failure
The last event before the EOF is the diagnostic signal:
| Last event in the log | What it means |
|---|---|
WRITE: ... Handshake (ClientHello), then EOF |
The peer rejected the ClientHello itself: protocol version, cipher suites, SNI, or a middlebox. |
READ: ... ServerHello, then EOF |
The peer accepted the hello and died during certificate or key exchange — unsupported signature algorithm, oversized certificate chain, or an MTU/PMTU black hole. |
READ: ... Certificate or ServerKeyExchange, then EOF |
Backend crash, or a proxy that only forwards the first few records. |
SEND ... ALERT: fatal, description = protocol_version |
Your client is rejecting the server because the server offered a version you have disabled. |
One caveat: the version shown in the log (TLSv1.2, TLSv1.3) is the record-layer version. A TLS 1.3 ClientHello is deliberately sent with a legacy TLS 1.2 record version, so do not conclude from it that TLS 1.3 was not attempted — check the supported_versions extension with ssl:handshake:verbose.
Step 3 — Probe the server with OpenSSL, not with Java
Establish what the endpoint actually speaks before changing any client code:
openssl s_client -connect api.example.com:443 -servername api.example.com -tls1_3 </dev/null
openssl s_client -connect api.example.com:443 -servername api.example.com -tls1_2 </dev/null
A successful run prints the negotiated parameters:
Protocol : TLSv1.3
Cipher : TLS_AES_256_GCM_SHA384
Read the results like this:
- Both succeed — the server is dual-stack. Your failure is cipher overlap, SNI, or a middlebox, not the protocol version.
- Only
-tls1_2succeeds — the server is TLS 1.2-only. A modern JDK still works, so look elsewhere. - Only
-tls1_3succeeds — the server is TLS 1.3-only. Any JDK without TLS 1.3 support fails with exactly this error. - Both fail — wrong port, wrong SNI name, or a proxy intercepting the connection.
Always pass -servername. Without it OpenSSL sends no SNI, and you can reproduce the same failure for entirely the wrong reason.
Enumerate the server’s cipher suites and protocols:
nmap -p 443 --script ssl-enum-ciphers api.example.com
Check the chain, issuer and expiry dates:
openssl s_client -connect api.example.com:443 -servername api.example.com -showcerts </dev/null | openssl x509 -noout -subject -issuer -dates
Compare against a different TLS stack on the same host:
curl -v --tls-max 1.2 https://api.example.com/ -o /dev/null
If curl and openssl both succeed and only Java fails, the problem is the JVM’s protocol/cipher configuration or its trust store — not the network path.
Step 4 — Compare the client: JDK version and TLS support matrix
Run java -version on the failing machine. Containers frequently ship a base image years older than the developer workstation.
| JDK build | TLS 1.3 | Default client protocols | Consequence for this error |
|---|---|---|---|
| JDK 6 / 7, JDK 8 before 8u261 | No | TLSv1, TLSv1.1, TLSv1.2 (varies by build) | Cannot talk to a TLS 1.3-only endpoint at all. Upgrade is the only fix. |
| JDK 8u261 – 8u281 | Yes (backport) | TLSv1, TLSv1.1, TLSv1.2, TLSv1.3 | TLS 1.3 available; legacy protocols still enabled. |
| JDK 8u291 and later | Yes | TLSv1.2, TLSv1.3 | TLS 1.0/1.1 disabled via java.security; TLS 1.0-only servers now fail. |
| JDK 11.0.x | Yes (JEP 332) | TLSv1.2, TLSv1.3 | Use 11.0.7+ to pick up later TLS and certificate fixes. |
| JDK 17 / 21 LTS | Yes | TLSv1.2, TLSv1.3 | 3DES, RC4, TLS 1.0/1.1 and SHA-1 certificates rejected by default. |
Print exactly what the running JVM supports and has enabled:
cat > TlsProbe.java <<'EOF'
import javax.net.ssl.*;
import java.util.*;
public class TlsProbe {
public static void main(String[] args) throws Exception {
SSLParameters p = SSLContext.getDefault().getSupportedSSLParameters();
System.out.println("protocols: " + Arrays.toString(p.getProtocols()));
System.out.println("ciphers: " + Arrays.toString(p.getCipherSuites()));
}
}
EOF
java TlsProbe.java
On JDK 8, compile first: javac TlsProbe.java && java TlsProbe.
Then check what the local policy has disabled — a hardened base image or a corporate java.security that blocks TLS 1.2 is a surprisingly common culprit:
grep -n 'jdk.tls.disabledAlgorithms' "$JAVA_HOME/conf/security/java.security"
On JDK 8 the path is $JAVA_HOME/jre/lib/security/java.security.
Step 5 — Apply the fix
Upgrade the JDK
This resolves the majority of cases. Move to JDK 8u261+ or 11.0.7+ for TLS 1.3 support, and preferably to a current 11/17/21 LTS build that also carries the certificate and cipher hardening.
Pin the protocols explicitly
java -Djdk.tls.client.protocols=TLSv1.3,TLSv1.2 -jar app.jar
Order does not matter for negotiation: the client offers every listed version and the server chooses. Do not try to enable TLS 1.3 with -Dhttps.protocols — that property only affects HttpsURLConnection and cannot express TLS 1.3.
Programmatically, on a raw socket:
SSLContext ctx = SSLContext.getInstance("TLS");
ctx.init(null, null, null);
SSLSocket socket = (SSLSocket) ctx.getSocketFactory().createSocket(host, 443);
socket.setEnabledProtocols(new String[] {"TLSv1.3", "TLSv1.2"});
socket.startHandshake();
Align cipher suites
java -Djdk.tls.client.cipherSuites=TLS_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 -jar app.jar
Treat this as a last resort. It usually masks a version mismatch and breaks again at the next server-side change. Get the server’s real list from nmap first.
Fix SNI
Connect by hostname, never by IP. If an IP is unavoidable, set the name explicitly:
SSLParameters params = socket.getSSLParameters();
params.setServerNames(Collections.singletonList(new SNIHostName("api.example.com")));
socket.setSSLParameters(params);
Keep TLS 1.2 enabled on the server during migration
In nginx: ssl_protocols TLSv1.2 TLSv1.3;. Do not go TLS 1.3-only while Java 8 clients are still in the fleet.
Troubleshooting: real error messages and what they mean
| Message | Reported by | Meaning and fix |
|---|---|---|
SSLHandshakeException: Remote host closed connection during handshakeCaused by: java.io.EOFException: SSL peer shut down incorrectly |
Client JSSE | Peer closed TCP with no alert. Work through protocol → cipher → SNI → middlebox in that order. |
javax.net.ssl.SSLException: Received fatal alert: protocol_version |
Server | A clean version rejection. Upgrade the client JDK, or lower the server’s minimum protocol. |
SSLHandshakeException: Received fatal alert: handshake_failure |
Server | No shared cipher suite, or the server cannot satisfy the client’s signature algorithms. |
SSLHandshakeException: No appropriate protocol (protocol is disabled or cipher suites are inappropriate) |
Client JSSE | Local jdk.tls.disabledAlgorithms blocks the only protocol the server offers — usually a TLS 1.0/1.1-only server. |
java.net.SocketException: Connection reset / Broken pipe |
TCP | RST from the peer or a middlebox. Capture packets and check IPS / load-balancer logs. |
javax.net.ssl.SSLException: Unsupported or unrecognized SSL message |
Client JSSE | You are speaking TLS to a plaintext port, or an HTTP proxy answered the CONNECT. |
sun.security.validator.ValidatorException: PKIX path building failed |
Client trust | A different problem: missing CA in the trust store. Unrelated to protocol settings. |
java.security.cert.CertificateException: No subject alternative names present |
Client trust | Hostname mismatch — frequently the symptom of connecting by IP address. |
When logs are ambiguous, capture the wire:
sudo tcpdump -i any -s 0 -w tls.pcap host api.example.com and port 443
In Wireshark, filter on tls.handshake.type == 1. If you see the ClientHello followed by a RST or FIN and no ServerHello, the decision was made by the peer or a device in the path, and no client-side cipher tuning will help.
Middleboxes, proxies and load balancers
- TLS-inspecting proxies terminate TLS with their own stack. If the proxy tops out at TLS 1.2 and the origin demands 1.3, you get an EOF right after ClientHello while the proxy’s own logs look clean.
- Java proxy settings are honoured via
https.proxyHost/https.proxyPortand, on some platforms, the system proxy. Test with-Djava.net.useSystemProxies=falseand no proxy properties to rule it out. - Load balancers configure the client-facing and backend legs separately.
openssl s_clientagainst the VIP can show TLS 1.3 while the backend pool is TLS 1.2-only, and the error still surfaces at the client. - SNI-based routing sends unknown or missing SNI to a default backend, or simply drops the connection.
- MTU/PMTU black holes break the handshake after ServerHello when the certificate chain is large: the log shows ServerHello then EOF, and small-payload tests pass.
Fast isolation: run the same request from the same host with curl, with openssl s_client, and with your Java client. Both non-Java tools working while Java fails points at client configuration; all three failing points at the network path.
FAQ
Is this caused by an expired or untrusted certificate?
No. Certificate problems produce PKIX path building failed or certificate expired after the handshake has progressed to the Certificate message. An EOF immediately after ClientHello happens before any certificate is validated.
Why does curl work but my Java client does not?
Different TLS stacks with different defaults. curl/OpenSSL typically enables TLS 1.3, sends SNI, and uses a broad cipher list; the JVM uses its own java.security policy and cacerts trust store, which on older builds may have TLS 1.2 disabled or only TLS 1.0/1.1 available.
Will upgrading the JDK always fix it?
No. It fixes protocol-version mismatches, which are the most common cause. If the endpoint requires a client certificate, blocks your egress IP, or a proxy is resetting the connection, a newer JDK changes nothing.
Should I just re-enable TLS 1.0/1.1 to make it work?
Only as a short-lived, documented exception. Remove TLSv1 from jdk.tls.disabledAlgorithms in java.security, and schedule the server upgrade — TLS 1.0/1.1 are deprecated and fail compliance audits.
Does -Dhttps.protocols=TLSv1.2 enable TLS 1.3?
No. That property applies only to HttpsURLConnection and accepts TLS 1.2 and below. Use -Djdk.tls.client.protocols or SSLParameters.setProtocols() instead.
Why does it fail only in Docker or CI, not on my machine?
The container is probably running a different JRE — often an old base image with JDK 8 before 8u261, or a distribution build with a hardened java.security. Run java -version and the TlsProbe snippet inside the container and compare the two.
It fails intermittently. What changes between attempts?
Multiple backend nodes with different TLS configurations, session resumption across a connection pool, or a load balancer whose health checks are flapping. Log the peer address with each attempt (socket.getInetAddress()) and correlate failures against it.