Error Knowledge Base Maven SSL_HANDSHAKE_FAILURE

SSLHandshakeException: Received fatal alert: handshake_failure

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

Where the Request Failed

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

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.

Examples

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

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;

Need help or found a mistake? Contact RepoFlow support for questions.

Join our mailing list