What does maven:SSL_HANDSHAKE_FAILURE mean?

The JVM running Maven could not complete the TLS handshake with the repository, so Maven cannot download artifacts over HTTPS.

SSLHandshakeException: Received fatal alert: handshake_failure

Q: How do I prevent maven:SSL_HANDSHAKE_FAILURE in CI?

Standardize Java runtimes for builds and keep them updated. Distribute corporate CAs and proxy configuration to developer machines, CI runners, and build images. Prefer an internal repository manager to shield builds from external TLS and proxy variability.

Q: How can I manually validate maven:SSL_HANDSHAKE_FAILURE?

Confirm which Java runtime Maven is using: `mvn -v` (Java version and vendor matter). Confirm the failing repository host and URL from the build output or `mvn -X`. Compare the Java runtime used locally, in CI, and in any container base image involved in the build. If you are on a corporate network, determine whether HTTPS is intercepted (corporate CA required) or whether a proxy is required.

Fix it fast

Most likely: The JVM running Maven cannot negotiate TLS with the repository. The common causes are an old Java runtime, a corporate TLS proxy, an untrusted CA, or a repository server with incompatible TLS settings.

1. Confirm this is your error

javax.net.ssl.SSLHandshakeException: Received fatal alert: handshake_failure
javax.net.ssl.SSLHandshakeException: Remote host terminated the handshake

2. Check the cause

mvn -v
mvn -X -DskipTests package
openssl s_client -showcerts -connect <host>:443 -servername <host> </dev/null
mvn -q help:effective-settings

3. Apply the safe fix

# First make sure Maven is using a modern Java runtime.
mvn -v

# If your network intercepts TLS, use a dedicated trust store for the corporate/root CA.
keytool -importcert -alias repo-ca -file /path/to/ca.pem -keystore /path/to/truststore.jks
MAVEN_OPTS="-Djavax.net.ssl.trustStore=/path/to/truststore.jks -Djavax.net.ssl.trustStorePassword=<password>" mvn -U -DskipTests package

4. Verify it works

mvn -DskipTests package
mvn -q -Dartifact=groupId:artifactId:version dependency:get

Don't use unsafe shortcuts

Do not treat this as a Maven credentials problem, the TLS handshake fails before authentication.
Do not disable certificate checks to get the build moving.
Do not import certificates into a different JDK than the one shown by mvn -v.

Where the Request Failed

Maven is telling you the request failed before it got a clean response back. Treat the connection path and the failing environment as the first suspects, not the package or image name.

Fix certificate trust and TLS

Start by proving the failing machine can reach the right host cleanly. Until DNS, routing, proxy, and trust look sane in that exact environment, retrying the install or pull is mostly noise.

Upgrade the Java runtime used by Maven first, because outdated TLS defaults are a common root cause.

If you are behind a corporate TLS proxy, import the corporate root CA into a dedicated trust store and point Maven at it via MAVEN_OPTS or .mvn/jvm.config.

If you control the repository, fix TLS configuration so it serves a complete certificate chain and modern TLS settings.

Compare behavior between networks (office or VPN versus hotspot) to isolate proxy interception from server-side TLS issues.

Avoid editing the global JDK trust store when a build-specific trust store is enough.

Manual TLS and Java runtime checks

Confirm which Java runtime Maven is using:mvn -v (Java version and vendor matter).

Confirm the failing repository host and URL from the build output or mvn -X.

Compare the Java runtime used locally, in CI, and in any container base image involved in the build.

If you are on a corporate network, determine whether HTTPS is intercepted (corporate CA required) or whether a proxy is required.

Why It Happens

Usually this comes down to your Java runtime is too old for the repository's TLS requirements (for example, TLS 1.2+ only), a corporate proxy/VPN intercepts HTTPS and presents certificates that your JVM does not trust, the repository server is misconfigured (incomplete certificate chain or unsupported cipher suite), or system time is wrong, causing certificate validity checks to fail.

Prove the Failing Environment Can Reach It

Re-run the original Maven goal and confirm artifact downloads succeed without SSLHandshakeException, and confirm Maven can download at least one artifact from the previously failing host.

Why TLS handshakes fail in Maven

This is the part worth understanding if the quick fix did not hold. It explains what Maven is trying to do at the moment the error appears.

Maven relies on the Java runtime's TLS implementation to connect to HTTPS repositories. Handshake failures can be caused by incompatible TLS versions/ciphers, missing trusted CAs, proxies intercepting HTTPS, or server-side TLS misconfiguration.

This is different from a 401/403:the connection fails before Maven can authenticate or download metadata.

Prevent Repeat Connectivity Failures

To prevent this, standardize Java runtimes for builds and keep them updated, distribute corporate CAs and proxy configuration to developer machines, CI runners, and build images, and prefer an internal repository manager to shield builds from external TLS and proxy variability.

Docs and source code

github.com/apache/maven/blob/maven-3.9.6/maven-core/src/main/java/org/apache/maven/project/DefaultProjectDependenciesResolver.java

TLS handshake failures bubble up as a transfer failure message from the underlying resolver/wagon layer and are included in Maven's dependency resolution exception (e.getMessage()). - GitHub

String msg = "Could not resolve dependencies for project " + project.getId() + ": " + e.getMessage();
DependencyResolutionException dex = new DependencyResolutionException(msg, e);
dex.setResult(e.getResult());
throw dex;