PKIX path building failed

What the error actually means #

PKIX path building is Java’s implementation of chain validation: start at the certificate the server presented, find the certificate that signed it, then the one that signed that, and keep going until you reach a certificate the JVM already trusts. That set of already-trusted certificates is the truststore.

The message appears at the moment the walk runs out of road. Java holds a certificate, knows the name of its issuer, and has no certificate for that issuer — not in the chain the server sent, and not in its truststore.

So the usual situation is not that something is broken — it is that a CA which is perfectly legitimate on your network, typically a corporate root or a TLS-inspecting proxy, was never taught to the JVM.

Step 1 — see what the server actually sends #

Before importing anything, find out which certificates are in play. The last certificate in this output is the highest CA the server offers, and it is the one whose issuer must be trusted:

openssl s_client -connect repo.example.com:443 -servername repo.example.com -showcerts </dev/null

Read the subject and issuer of every certificate returned, top to bottom:

openssl s_client -connect repo.example.com:443 -servername repo.example.com -showcerts </dev/null 2>/dev/null \
| grep -E "^ *[0-9]+ s:|^ *i:"

0 s:CN=repo.example.com
i:C=US, O=Example Corp, CN=Example Corp Issuing CA
1 s:C=US, O=Example Corp, CN=Example Corp Issuing CA
i:C=US, O=Example Corp, CN=Example Corp Root CA

In that example the top certificate is issued by Example Corp Root CA, which the server does not send — correctly, since a root is supposed to come from the truststore. That root is what you need to import.

Step 2 — confirm the JVM does not already trust it #

Java 9 and later can list the active cacerts without you locating the file:

keytool -list -cacerts -storepass changeit | grep -i "example corp"

On Java 8, name the file explicitly:

keytool -list -keystore "$JAVA_HOME/jre/lib/security/cacerts" -storepass changeit \
| grep -i "example corp"

No output means the CA is genuinely absent, which confirms the diagnosis.

Step 3 — get the CA certificate as a file #

If someone can hand you the root CA in PEM form, use that — it is the trustworthy path. Otherwise you can extract the top certificate from the chain the server sent, but only after confirming out of band that it is the CA you expect:

openssl s_client -connect repo.example.com:443 -servername repo.example.com -showcerts </dev/null 2>/dev/null \
| awk '/BEGIN CERT/{n++} n{print > ("cert-" n ".pem")} /END CERT/{if (n) close("cert-" n ".pem")}'

Confirm the fingerprint of what you are about to import:

openssl x509 -in root-ca.crt -noout -subject -issuer -fingerprint -sha256

A root CA is self-signed, so its subject and issuer will be identical.

Step 4 — import it #

You have two options, and they are not equally good.

cp "$JAVA_HOME/lib/security/cacerts" truststore.jks
keytool -importcert -trustcacerts -noprompt \
-alias example-corp-root \
-file root-ca.crt \
-keystore truststore.jks \
-storepass changeit

java -Djavax.net.ssl.trustStore=/opt/app/truststore.jks \
   -Djavax.net.ssl.trustStorePassword=changeit \
   -jar app.jar

sudo keytool -importcert -trustcacerts -noprompt \
-alias example-corp-root \
-file root-ca.crt \
-cacerts -storepass changeit

sudo cp root-ca.crt /usr/local/share/ca-certificates/example-corp-root.crt
sudo update-ca-certificates

Restart the JVM afterwards. The truststore is read once during initialisation, so a running process will keep failing no matter what you import.

When the chain is incomplete rather than untrusted #

If Step 1 showed a public CA and only one certificate came back, the server is at fault: it is not sending its intermediates. Browsers paper over this by fetching the missing intermediate from the Authority Information Access extension, and Java does not — unless you ask it to:

java -Dcom.sun.security.enableAIAcaIssuers=true -jar app.jar

That flag makes Java fetch missing intermediates the way a browser does, and it resolves this class of failure without importing anything. It is a workaround for someone else’s misconfigured server, not a substitute for fixing the chain, and it costs an outbound HTTP request on the first handshake.

Setting the flags for common tools #

The JVM that needs the truststore is the one opening the connection, which is often not the one you launched:

Still failing after the import #

Turn on the JSSE handshake log. It names the truststore that was actually loaded and every anchor in it, which usually reveals that a different JVM, or a different store, is in play:

java -Djavax.net.debug=ssl:handshake:trustmanager -jar app.jar 2>&1 | head -60

The three things that log tends to expose, in order of frequency: the application runs on a different JDK from the one you imported into; the truststore path is set but the process never restarted; or an outbound proxy is terminating TLS and presenting a chain you have not seen yet.

What not to do #