Symptoms & Diagnosis
The “sun.security.validator.ValidatorException: PKIX path building failed” error in Java 21 occurs during an SSL/TLS handshake. It signifies that the Java Virtual Machine (JVM) cannot verify the certificate chain provided by a remote server.
This typically happens when your application attempts to connect to an HTTPS endpoint, an LDAPS server, or a private Maven repository. If the server’s certificate is self-signed or issued by an internal Certificate Authority (CA) not present in the Java truststore, the connection is aborted for security reasons.
| Symptom | Technical Impact |
|---|---|
| SSLHandshakeException | The connection is terminated before data transfer begins. |
| ValidatorException | The sun.security.validator fails to build a valid path to a trusted root. |
| Failed API Calls | External REST or SOAP services return connection errors. |
Troubleshooting Guide
1. Extract the Remote Certificate
First, you must obtain the public certificate from the server you are trying to reach. You can use the OpenSSL command-line tool to fetch the certificate directly from the terminal.
openssl s_client -showcerts -connect example.com:443 < /dev/null | openssl x509 -outform DER > remote_cert.cer2. Identify the Java 21 Truststore Path
Java 21 stores trusted certificates in a file named cacerts. You need to identify the exact path within your JDK installation. Usually, it is located in the lib/security directory.
# Example path for Windows
C:\Program Files\Java\jdk-21\lib\security\cacerts
# Example path for Linux/macOS
/usr/lib/jvm/java-21-openjdk/lib/security/cacerts3. Import the Certificate into Cacerts
Use the keytool utility provided with the JDK to import the certificate. The default password for the Java keystore is changeit.
keytool -import -alias myservercert -keystore "PATH_TO_CACERTS" -file remote_cert.cerAfter running the command, type “yes” when asked if you trust the certificate. Restart your Java application to apply the changes.
Prevention
To prevent certificate path issues in Java 21, always ensure your production servers use certificates from recognized Public Certificate Authorities. Java’s default truststore is updated frequently to include modern CA roots.
In containerized environments, such as Docker, automate the certificate import process within your Dockerfile. This ensures that every deployment includes the necessary trust anchors without manual intervention.
Finally, consider using the JVM argument -Djavax.net.ssl.trustStore if you prefer to maintain a separate, application-specific truststore rather than modifying the global JDK cacerts file.