DEV Community

Deep Fix
Deep Fix

Posted on

How to Resolve SSL/TLS Certificate Handshake Failures – Troubleshooting Guide for Developers

#ssl #tls #devops #troubleshoot

How to Resolve SSL/TLS Certificate Handshake Failures – Troubleshooting Guide for Developers

Overview

SSL/TLS handshake failures are a common source of downtime for web services. This article walks you through the most frequent causes, how to diagnose them with practical commands, and step‑by‑step remediation strategies that you can apply in minutes.

Common Causes

  • Expired or not‑yet‑valid certificate
  • Hostname mismatch (CN/SAN does not match the request host)
  • Incomplete certificate chain (missing intermediate CA)
  • Unsupported protocol version or cipher suite
  • Incorrect server configuration (e.g., SSLVerifyClient set to require when client cert is absent)

Step‑by‑Step Diagnosis

1. Inspect the server certificate 

openssl s_client -connect example.com:443 -servername example.com -showcerts
Enter fullscreen mode Exit fullscreen mode

The output shows the leaf certificate, any intermediates, and the verification status. Look for verify return code:0 (ok).

2. Test protocol and cipher support 

curl -vI https://example.com
Enter fullscreen mode Exit fullscreen mode

If you see SSL connection reset or SSL: handshake failed, note the TLS version reported.

3. Check hostname verification 

openssl s_client -connect example.com:443 -servername wrong-host.com
Enter fullscreen mode Exit fullscreen mode

A mismatch will produce hostname mismatch warnings in the verification section.

4. Review server logs

  • NGINX: error.log – look for sslhandshake messages.
  • Apache: error_log – search for SSL handshake failed.
  • Java apps: enable javax.net.debug=ssl for detailed traces.

Fixes

Renew or replace an expired certificate 

# Using Certbot for Let’s Encrypt
certbot renew --force-renewal -d example.com
Enter fullscreen mode Exit fullscreen mode

Add missing intermediate certificates

Combine your leaf and intermediate certs into a single PEM file:

cat cert.pem intermediate.pem > fullchain.pem
# Update your web server config to point to fullchain.pem
Enter fullscreen mode Exit fullscreen mode

Adjust protocol and cipher settings

For NGINX:

ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers HIGH:!aNULL:!MD5;
Enter fullscreen mode Exit fullscreen mode

For Apache:

SSLProtocol all -SSLv3 -TLSv1 -TLSv1.1
SSLCipherSuite HIGH:!aNULL:!MD5
Enter fullscreen mode Exit fullscreen mode

Resolve hostname mismatches

Ensure the Common Name (CN) or Subject Alternative Names (SAN) include the exact host used by clients. Regenerate the CSR if needed:

openssl req -new -key key.pem -out request.csr -subj "/CN=example.com"
Enter fullscreen mode Exit fullscreen mode

Automating the Fix

You can use our ready‑made script to rebuild the certificate chain and restart the service automatically. Download the pre‑configured script here. Or Get the complete patch tool for a one‑click remediation. For more details, Access the full repository fix.

Preventive Measures

  • Monitor certificate expiry with tools like certwatch or monitoring platforms.
  • Enable OCSP stapling to improve revocation checking.
  • Enforce a minimum TLS version (TLS 1.2) in all services.
  • Automate deployments with CI/CD pipelines that include TLS validation steps.

By following these diagnostics and remediation steps, you can quickly restore secure connectivity and reduce the risk of future handshake failures. Happy debugging!

Top comments (0)