Skip to main content
search
Error Logs

Error Log: SSLHandshakeException – The insecure connection

By November 19, 2025No Comments

Error Log: You will see this error in your client application’s logs (e.g., Logstash, Filebeat, your custom code) when it tries to connect to your cluster’s HTTPS endpoint.

None
javax.net.ssl.SSLHandshakeException: 
  PKIX path building failed: 
  sun.security.provider.certpath.SunCertPathBuilderException: 
  unable to find valid certification path to requested target

Or a simpler variation:

None
javax.net.ssl.SSLHandshakeException: Received fatal alert: certificate_unknown

Or when using cURL:

None
curl: (60) SSL certificate problem: self signed certificate
More details here: https://curl.haxx.se/libcurl/c/libcurl-errors.html

Why… is this happening? This error means your client (your application, cURL, etc.) cannot establish a secure TLS (SSL) connection to your OpenSearch node. It’s a failure of trust.

The most common reason, by far, is that your OpenSearch cluster is using self-signed certificates (like those generated by the install_demo_configuration.sh script or your own internal tools), and your client has not been configured to trust the “issuer” of those certificates.

Other causes include:

  1. Certificate Mismatch: The certificate’s “Common Name” (CN) or “Subject Alternative Name” (SAN) does not match the hostname or IP address your client is trying to connect to.
  2. Expired Certificate: The server’s certificate has expired.
  3. Client-Side Keystore: Your client is configured to use a truststore (e.g., a Java Keystore), but that truststore doesn’t contain the root CA certificate needed to validate the server’s cert.
  4. Protocol Mismatch: The client and server can’t agree on a TLS version (e.g., client is trying TLSv1.1, server requires TLSv1.3).

Best Practice:

  1. For Demo/Test (Insecure): The quick and insecure fix for tools like cURL or Python scripts is to disable SSL verification.
    • cURL: Use the -k or --insecure flag.
    • Clients: Most clients (like Python’s requests library) have an option like verify=False. Do not do this in production.
  2. For Production (Secure): The correct fix is to make the client trust your cluster’s certificates.
    • Find your Root CA: Locate the root Certificate Authority (CA) file that was used to sign your node certificates (e.g., root-ca.pem).
    • Configure Your Client:
      cURL: Use curl --cacert /path/to/root-ca.pem https://...
    • Java/Logstash: Import the root-ca.pem into the client’s Java truststore (or a new truststore) and configure the truststore_path and truststore_password in your client’s settings.
    • Other Clients: Point your client’s “ca_certs” or equivalent setting to the root-ca.pem file.
  3. Check Certificate SANs: When generating your certificates, ensure the “Subject Alternative Name” (SAN) list includes all hostnames and IP addresses that your clients will use to connect to the nodes.

What else can I do? TLS is notoriously tricky. If you’re stuck in a handshake failure, the OpenSearch community forums are a great place to post your certificate details (not the private keys!) and client configuration. For help setting up a robust, secure cluster, contact us in The OpenSearch Slack Channel in #General.

Author