A Java client fails the TLS handshake with SSLHandshakeException
javax.net.ssl.SSLHandshakeExceptionShort answer
SSLHandshakeException means the TLS handshake stopped before any data moved. In a Java client the usual reasons are that the server certificate is unknown to the truststore the JVM loaded, the JVM loaded a different or empty truststore than you think, the system clock is wrong, or client and server could not agree on a TLS protocol version. Turn on handshake debugging first: it names which one.
Fix it fast
1Find out which cause you have
Run the failing program once with JSSE handshake tracing. The output shows each certificate the server sent and which truststore file was loaded, which separates the causes below.
java -Djavax.net.debug=ssl:handshake -jar app.jar2Match what you see, then jump to its fix
- 1
The trace shows a certificate arriving from the server and the exception is a CertificateException while handshaking.The server certificate is unknown to the truststoreFix - 2
You imported the certificate, but the error stays, or it only fails in one environment (an app server, a container, a service).The JVM loads a different truststore than you expectFix - 3
The certificate chain is one you trust, but the handshake still fails with a CertificateException, mostly on a fresh VM, container or device.The system clock is wrongFix - 4
The connection is closed right after the client sends its ClientHello.Client and server do not share a TLS protocol versionFix
- 1
What does the error look like?
javax.net.ssl.SSLHandshakeExceptionSocket Disconnected After Sending ClientHello Message
Cause 1 of 4
The server certificate is unknown to the truststore
1Check
This is the usual cause when the server uses a private CA or a self-signed certificate. The received certificate is unknown to the trust mechanism, so Java refuses it. Compare the issuer in the trace with the CAs in the default truststore.
keytool -list -cacerts -storepass changeit | head2Fix
Import the CA certificate (not the leaf, when you have the CA) into the truststore the app uses. The -cacerts option points keytool at the JDK default truststore; the cacerts password is documented as changeit unless an administrator changed it. For one application it is cleaner to build a separate truststore with -keystore and point the app at it (see the next cause).
keytool -importcert -alias my-private-ca -file ca.pem -cacerts3Verify
Run the same program again; the handshake trace ends without an exception.
java -Djavax.net.debug=ssl:handshake -jar app.jarConfirmed by docs.oracle.com
Cause 2 of 4
The JVM loads a different truststore than you expect
1Check
If javax.net.ssl.trustStore is set, only that file is used. If it is set to a path that does not exist, JSSE ends up with no trusted CAs at all. If the property is not set, Java uses jssecacerts when it exists, otherwise cacerts under the JDK. So a stray property, or a jssecacerts file, can hide the cacerts you edited.
ps -o args= -p <pid-of-java> | tr ' ' '\n' | grep -i truststore
ls "$JAVA_HOME/lib/security/"2Fix
Point the property at the file that really holds your CA, with its password, or remove the stray property so the default is used. Make sure the JDK that runs the app is the JDK you edited.
java -Djavax.net.ssl.trustStore=/etc/app/truststore.p12 \
-Djavax.net.ssl.trustStorePassword=changeme \
-jar app.jar3Verify
Restart the app with handshake tracing and check that the trace reads the truststore file you named.
java -Djavax.net.debug=ssl:handshake -Djavax.net.ssl.trustStore=/etc/app/truststore.p12 -Djavax.net.ssl.trustStorePassword=changeme -jar app.jarConfirmed by docs.oracle.com
Cause 3 of 4
The system clock is wrong
1Check
The JSSE guide lists a wrong system clock as a second cause of a CertificateException during the handshake: a certificate is outside its validity dates when the clock is far off.
date -u
timedatectl status2Fix
Correct the clock and keep it synchronised with NTP.
sudo timedatectl set-ntp true3Verify
Run the client again after the clock is right.
date -uConfirmed by docs.oracle.com
Cause 4 of 4
Client and server do not share a TLS protocol version
1Check
Some servers drop a connection when the ClientHello carries a protocol version they do not support. List the protocols your code or JVM settings allow.
grep -rn "jdk.tls.client.protocols\|https.protocols\|setEnabledProtocols\|SSLContext.getInstance" src/2Fix
Adjust the enabled protocols on the client. The JSSE guide names these places: the https.protocols system property for HttpsURLConnection, the jdk.tls.client.protocols system property, SSLContext.getInstance and SSLEngine.setEnabledProtocols. Restrict to the versions the server really supports instead of switching security off.
java -Djdk.tls.client.protocols="TLSv1.2,TLSv1.3" -jar app.jar3Verify
Run again with handshake tracing; the connection is no longer closed after the ClientHello.
java -Djavax.net.debug=ssl:handshake -Djdk.tls.client.protocols="TLSv1.2,TLSv1.3" -jar app.jarConfirmed by docs.oracle.com
How do I stop it coming back?
- Keep private CA certificates in a truststore file that ships with the app, and name it with javax.net.ssl.trustStore, instead of editing the JDK's cacerts by hand.
- Log the JVM arguments at start-up so a stray trustStore property is easy to see.
- Run NTP on every server and container host.
- Never disable certificate or hostname checks to make an error go away; fix the trust.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Related fixes
Back end
Android gets HTML instead of JSON from a PHP API
org.json.JSONException: Value <br of type java.lang.String cannot be converted to JSONObject
The response body is not JSON.
2 causes, each with a fixBack end
The AWS SDK for Java cannot find credentials, and AwsCredentials.properties does nothing
software.amazon.awssdk.core.exception.SdkClientException: Unable to load credentials from any of the providers in the chain
AwsCredentials.properties on the classpath is an old convention: the default provider chain of the AWS SDK for Java does not read it.
4 causes, each with a fixBack end
Composer or PHP stream fails with certificate verify failed
SSL certificate problem: unable to get local issuer certificate
PHP could not check the server's TLS certificate against a trusted CA file.
3 causes, each with a fixBack end
Gradle runs no Cucumber scenarios from my feature files
Feature files exist under src/test but nothing runs
Cucumber runs on the JUnit Platform, so Gradle must call useJUnitPlatform() and have the cucumber-junit-platform-engine on the test classpath.
4 causes, each with a fixBack end
A Gradle build fails on classes that use Lombok annotations
Error: Annotation processors must be explicitly declared now.
Lombok is two things for Gradle: a compile-time library and an annotation processor.
3 causes, each with a fixBack end
Gradle 8 fails on Report destination: switch to outputLocation
What went wrong: 'java.io.File org.gradle.api.reporting.ConfigurableReport.getDestination()'
Gradle 8.0 removed the deprecated destination and enabled properties of the Report type.
2 causes, each with a fix