Introduction
The error “pkix path building failed” generally happens while working with Java client applications and HTTPS web services or APIs. This is generally accompanied by another error message saying - “unable to find valid certification path to requested target‘’. The error is thrown by sun.security.provider.certpath.SunCertPathBuilderException.
The class is responsible for validating the SSL certificates before allowing the client application to connect to an HTTPS URL. The log messages for this error generally appear as below.
caused by: javax.net.ssl.SSLHandshakeException: sun.security.validator.ValidatorException: PKIX path building failed:sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target '
The above error is not easy to troubleshoot since it can originate while doing seemingly unrelated things. Since it has to do with accessing an HTTPS service, it can be thrown by any library that accesses a secured URL. And it can happen even with well-known libraries trying to access secure and standard URLs. It is now time to look at the situations where developers encounter this problem.
The most common instance of facing this error is while dealing with package building processes and auto-deployment modules that access library files from cloud sources. This error is typically found while trying to access maven software repositories by client build utilities. The reason is an invalid SSL certificate configuration at the client system. On another note, If you are looking for a repository management system that is reliable and easy to use, consider PackageCloud.
You can check out the PackageCloud here.
The error can also be thrown by third-party client libraries while trying to use their parent web services for fetching data. For example, SDKs provided by cloud services like Salesforce fetch data from Salesforce APIs. An invalid certificate configuration at the client system can result in these libraries throwing the error. Another frequent scenario that can result in this error is while dealing with services secured by self-signed certificates.
Any Java application that tries to fetch data from such a URL will face this problem. The reason is that Java will not trust self-signed certificates unless specifically configured. You may also come across this error after upgrading, reinstalling, or changing the configurations of your Java installation, At times, the certificate configurations in Java’s internal trust store get messed up during these activities and can result in this error.
What is the problem when you see “pkix path building failed”
In the simplest of terms, the error occurs when the Java framework fails to validate the SSL certificate of the URL that is being accessed. Any Java application, be it a third party library, a build process, or even a custom code, when it tries to access an HTTPS URL, the underlying Java run time will first check whether the certificate of the domain is known to it. This is done by matching the certificate of the domain with a list that Java keeps internally. This list is called a trust store. Trust store enables Java to abort connections to any malicious URL and prevents client system compromises that can originate from such malicious entities.
A logical extension of this behavior is that all URLs that use a self-signed certificate will end up in trouble. This is because a self-signed certificate will never be part of the Java trust store unless it has been explicitly added. But then, how does this error happen in the case of libraries or processes that try to access well-known domains?
A common cause for this behavior is a corrupted trust store in your Java client machine. This can happen because of an installation attempt going wrong or even a failed upgrade attempt. Nevertheless, your Java client applications will fail to connect to HTTPS URLs, till the trust store is fixed.
Another possibility is when the URL or domain uses a certificate authority that is not very popular. This can also happen when there are many intermediate certificate authorities involved in the chain of certificates used by the domain. In such cases, Java fails to validate authenticity unless all intermediate certificates are known to it. This will not happen in the case of domains that use well-known root certificate authorities or intermediate certificate authorities.
If your problem is with the certificate chain, then fixing it requires some level of knowledge about SSL certificate chains, intermediate CA, and Root CA. Let's address this concept in the next section.
Understanding SSL encryption and certificates
The SSL certificate is what makes communication over an HTTPS channel secure. It establishes the identity of the domain that uses it. All communication through HTTPS is encrypted using a private key. A public key that is associated with the domain is expected to be with the client who is receiving the encrypted data. The client then verifies the authenticity of the data by verifying whether it is able to successfully use the public key on the data. How does the website or the domain get access to this private key and public key? This is where certificate authority comes into the picture.
The domain that wants to use HTTPS first places a certificate signing request with a certificate authority to get access to the private and public keys. The Certificate authority uses a root certificate to generate the key pair for the domain. This root certificate is approved by standard trust stores that are managed by Google, Mozilla, Microsoft, etc. The assumption is that all intermediate certificates generated by such a root certificate are valid one.
What makes things complicated is that the certificate authorities will not always use the root certificate to generate the certificates for domains. Instead, they first generate an intermediate certificate using the root certificate. These intermediate certificates are then used to provide key pairs for domains that place a certificate signing request. This is done so that, in the event of a catastrophe or leak of the certificate, only the certificates that originated from that particular intermediate certificate need to be invalidated.
If a root certificate is used for all clients, the risk involved will be too high and can become unmanageable in case of a breach. This concept of intermediate certificates and root certificates leads to a certificate chain rather than dealing with a single certificate. From the perspective of a client application, certificate chains make the validation job tougher and complex. At times, the client applications failed to recognize the intermediate certificates and throw a ‘pkix path building failed’ error.
The last bit we need to understand before getting into the fix for ‘pkix path building failed’ error message is the concept of a self-signed certificate. These certificates are generated by domain owners on their own without depending upon any certificate authority. Using a self-signed certificate does not mean that the encryption can be easily breached. It only means that without the backing of a certificate authority, there is no way for the client applications to verify that the entity at the other end is indeed the expected one. But what if both the client and server are managed by the same organization ? In that case, it is absolutely fine to use a self-signed certificate. But for java client applications to use URLs managed by self-signed certificates, it has to be specifically added to their internal trust store.
How to solve “pkix path building failed”
Ensuring that the error is a result of what we discussed in the above section is the first step towards solving it. This error can also arise from a very strict network configuration or firewall rule too. To eliminate this possible head to your favorite browser and try to access the URL that creates problems. If the browser is able to process it without errors, then it means the problem is with the client application’s certificate configuration.
1. Once it is confirmed that the problem is indeed with the certificate configuration, the next step is to download the certificate used by the server. This can be done through the browser. This is done so that we can add the certificate manually to the trust store. In the simplest of cases, the downloaded certificate could be the root certificate, but in most cases, there will be a certificate chain and intermediate CAs.
In the case of Chrome browser, click the lock icon next to the URL bar and click on the Certificate link and click details. In the details section, you can view a button to export the certificate. After clicking it ensure that DER encoded binary is selected as the format for export.
2. If you don’t want to download the certificate using a browser, it can be done using the below command too.
openssl s_client -showcerts -connect <URL:443>
The output will be as follows. It contains all the certificates involved in the chain.
CONNECTED(00000003)
depth=2 C = US, O = Google Trust Services LLC, CN = GTS Root R1
verify return:1
depth=1 C = US, O = Google Trust Services LLC, CN = GTS CA 1C3
verify return:1
depth=0 CN = *.google.com
verify return:1
---
Certificate chain
0 s:CN = *.google.com
i:C = US, O = Google Trust Services LLC, CN = GTS CA 1C3
-----BEGIN CERTIFICATE-----
O/B/H91EeIB4q+nmRO
tYxFcW8qt9iyYP/rqp2q6lBmzkPLEpJH....
-----END CERTIFICATE-----
Copy each of the certificates as a file with unique names. You should have both the BEGIN CERTIFICATE and END CERTIFICATE part in files.
3. We can now add the certificates to the internal Java trust store. Keytool utility can be used to do this.
sudo keytool -importcert -keystore /usr/local/java/jdk1.8.0_60/jre/lib/security/cacerts -storepass changeit -file ~/Downloads/cert_file.crt -alias "root_cert"
The alias name should be unique for each certificate, The default password for the JRE trust store is ‘changeit’. If you have changed this password, ensure to use the correct password.
4. Once this is done, you can verify the certificates are indeed added using the below command.
keytool -list -keystore "/usr/local/java/jdk1.8.0_60/jre/lib/security/
You can now restart your client application or the process that triggered this error. If all steps are executed correctly, you should not face further errors.
Conclusion
The error ‘pkix path building failed’ is a tough one to troubleshoot since it needs elaborate knowledge on SSL certificates, root CAs and intermediate CAs. The fact that this error can be thrown even because of improper firewall or network configuration makes troubleshooting all the more difficult. This problem is very frequent while dealing with package managers, automated deployment processes, etc. The best way to avoid losing time stuck on such issues is to use a reliable package repository like Packagecloud that just works all the time.
You can checkout PackageCloud here.
