Fix 'PKIX Path Building Failed' in Java: Every Cause & Solution

Cause 4: JDK Upgrade Removed a CA

What’s happening: When you upgrade Java, the new JDK comes with its own cacerts file. Any custom CAs you imported into the old JDK’s cacerts are gone.

Diagnose:

# Check if the CA exists in the new JDK
keytool -list -keystore "$JAVA_HOME/lib/security/cacerts" -storepass changeit | grep -i "your-alias"

Fix — re-import after upgrade:

# If you kept the old cacerts, export and re-import:
keytool -exportcert -alias your-ca-alias \
  -keystore /path/to/old-jdk/lib/security/cacerts \
  -storepass changeit -file exported-ca.pem

keytool -importcert -trustcacerts -alias your-ca-alias \
  -file exported-ca.pem \
  -keystore "$JAVA_HOME/lib/security/cacerts" \
  -storepass changeit -noprompt

Prevent this: Keep a script that imports all required custom CAs, and run it after every JDK upgrade:

#!/bin/bash
# import-custom-cas.sh — run after JDK upgrades
CACERTS="$JAVA_HOME/lib/security/cacerts"
STOREPASS="changeit"

for cert in /opt/custom-certs/*.pem; do
  ALIAS=$(basename "$cert" .pem)
  keytool -importcert -trustcacerts -alias "$ALIAS" \
    -file "$cert" -keystore "$CACERTS" \
    -storepass "$STOREPASS" -noprompt 2>/dev/null
  echo "Imported: $ALIAS"
done

Cause 5: Custom TrustStore Not Configured

What’s happening: Your application specifies a custom trust store via javax.net.ssl.trustStore but the file is empty, doesn’t exist, or doesn’t contain the required CAs.

Diagnose:

# Check if your app sets a custom trust store
grep -r "trustStore" src/ config/ application.properties application.yml

# Check JVM arguments
ps aux | grep java | grep trustStore

Fix — ensure the custom trust store has the right CAs:

# List contents of the custom trust store
keytool -list -keystore /path/to/custom-truststore.jks -storepass yourpassword

# If empty, initialize it with the default CAs plus your custom ones:
cp "$JAVA_HOME/lib/security/cacerts" /path/to/custom-truststore.jks

# Then add your custom CA:
keytool -importcert -trustcacerts -alias custom-ca \
  -file your-ca.pem \
  -keystore /path/to/custom-truststore.jks \
  -storepass yourpassword -noprompt

Spring Boot Configuration

application.properties:

# Point to a custom trust store
server.ssl.trust-store=classpath:truststore.jks
server.ssl.trust-store-password=changeit
server.ssl.trust-store-type=JKS

# For outbound HTTPS calls (RestTemplate, WebClient):
# Set via JVM args instead:
# -Djavax.net.ssl.trustStore=/path/to/truststore.jks
# -Djavax.net.ssl.trustStorePassword=changeit

application.yml:

server:
  ssl:
    trust-store: classpath:truststore.jks
    trust-store-password: changeit
    trust-store-type: JKS

Programmatic configuration for RestTemplate:

import org.apache.http.ssl.SSLContextBuilder;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClients;
import org.springframework.http.client.HttpComponentsClientHttpRequestFactory;
import org.springframework.web.client.RestTemplate;

import java.io.File;
import javax.net.ssl.SSLContext;

// Load custom trust store
SSLContext sslContext = SSLContextBuilder.create()
    .loadTrustMaterial(
        new File("/path/to/truststore.jks"),
        "changeit".toCharArray()
    )
    .build();

CloseableHttpClient httpClient = HttpClients.custom()
    .setSSLContext(sslContext)
    .build();

RestTemplate restTemplate = new RestTemplate(
    new HttpComponentsClientHttpRequestFactory(httpClient)
);

This approach maintains full certificate validation while using a custom trust store. It does not disable security.

Maven and Gradle Build Fixes

Maven — PKIX error when downloading dependencies:

# Pass trust store to Maven via MAVEN_OPTS
export MAVEN_OPTS="-Djavax.net.ssl.trustStore=$JAVA_HOME/lib/security/cacerts -Djavax.net.ssl.trustStorePassword=changeit"

# Or in .mvn/jvm.config (project-level):
echo "-Djavax.net.ssl.trustStore=/path/to/cacerts" > .mvn/jvm.config
echo "-Djavax.net.ssl.trustStorePassword=changeit" >> .mvn/jvm.config

Gradle — PKIX error when downloading dependencies:

# In gradle.properties:
systemProp.javax.net.ssl.trustStore=/path/to/cacerts
systemProp.javax.net.ssl.trustStorePassword=changeit

# Or via environment variable:
export GRADLE_OPTS="-Djavax.net.ssl.trustStore=$JAVA_HOME/lib/security/cacerts -Djavax.net.ssl.trustStorePassword=changeit"

Both — if behind a corporate proxy:

Import the proxy CA into the JDK’s cacerts (see Cause 3 above). This is the cleanest fix because Maven and Gradle will automatically use the JDK’s default trust store.

Docker and Container Fixes

Dockerfile — import CA at build time:

FROM eclipse-temurin:21-jre

# Copy custom CA certificate
COPY corporate-ca.pem /tmp/corporate-ca.pem

# Import into Java's cacerts
RUN keytool -importcert -trustcacerts -alias corporate-ca \
    -file /tmp/corporate-ca.pem \
    -keystore $JAVA_HOME/lib/security/cacerts \
    -storepass changeit -noprompt && \
    rm /tmp/corporate-ca.pem

COPY app.jar /app/app.jar
ENTRYPOINT ["java", "-jar", "/app/app.jar"]

Kubernetes — mount CA as a secret:

apiVersion: v1
kind: Pod
metadata:
  name: java-app
spec:
  containers:
    - name: app
      image: your-app:latest
      env:
        - name: JAVA_OPTS
          value: "-Djavax.net.ssl.trustStore=/etc/ssl/custom/truststore.jks -Djavax.net.ssl.trustStorePassword=changeit"
      volumeMounts:
        - name: truststore
          mountPath: /etc/ssl/custom
          readOnly: true
  volumes:
    - name: truststore
      secret:
        secretName: java-truststore

Create the Kubernetes secret:

# Create trust store with your custom CA
keytool -importcert -trustcacerts -alias custom-ca \
  -file ca.pem -keystore truststore.jks \
  -storepass changeit -noprompt

# Create the secret
kubectl create secret generic java-truststore --from-file=truststore.jks

// DO NOT USE THIS IN PRODUCTION
// This disables ALL certificate checking — any attacker can intercept your traffic
TrustManager[] trustAllCerts = new TrustManager[] {
    new X509TrustManager() {
        public X509Certificate[] getAcceptedIssuers() { return null; }
        public void checkClientTrusted(X509Certificate[] certs, String authType) {}
        public void checkServerTrusted(X509Certificate[] certs, String authType) {}
    }
};

# From the command line
java -XshowSettings:all 2>&1 | grep "java.home"

# Then append /lib/security/cacerts (Java 9+) or /jre/lib/security/cacerts (Java 8)

keytool -importkeystore \
  -srckeystore cacerts -srcstoretype JKS \
  -destkeystore cacerts.p12 -deststoretype PKCS12 \
  -srcstorepass changeit -deststorepass changeit