SSL/TLS handshake errors prevent secure connections between clients and servers. When a handshake fails, browsers display non-bypassable error screens, interrupting user sessions and breaking API communications.

Here is a step-by-step diagnostic guide to identifying and fixing the most frequent handshake failures.

Common SSL/TLS Handshake Errors & Solutions

1. SSLERRORRXRECORDTOOLONG or ERRSSLPROTOCOLERROR

• Cause: The client attempted an encrypted HTTPS connection to a server port that is serving unencrypted plain HTTP traffic.
• Fix: Check your web server configuration (Nginx/Apache) to ensure listen 443 ssl is configured and that port 443 is not mapped to an unencrypted backend upstream.

2. TLS Handshake Failure / Cipher Suite Mismatch

• Cause: The client and server cannot agree on a mutually supported TLS protocol version or cipher suite.
• Fix: Update server configurations to support modern ciphers while maintaining backward compatibility:

`nginx
ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384;
`

3. NET::ERRCERTAUTHORITY_INVALID / Incomplete Certificate Chain

• Cause: The server is sending its leaf certificate but missing the intermediate CA certificate required to form a complete trust chain to a root CA.
• Fix: Ensure your web server serves the full-chain certificate file (fullchain.pem in Certbot) rather than just the leaf cert.pem.

4. SECERRORREVOKED_CERTIFICATE / OCSP Stapling Failure

• Cause: The certificate was revoked by the issuing CA, or OCSP stapling is misconfigured on the server causing validation timeouts.
• Fix: Check certificate revocation status and verify OCSP stapling settings in your web server config.

Diagnostic CLI Commands

Use OpenSSL from the command line to inspect handshake details directly:

`bash

Test handshake & view full certificate chain

openssl s_client -connect example.com:443 -servername example.com -showcerts

Test specific TLS version (e.g. TLS 1.2)

openssl sclient -connect example.com:443 -tls12 `

Free Online Diagnostics with CertificateGuardian

Need a quick, client-side diagnostic audit? Use our free SSL/TLS Connection Checker to test cipher support, inspect certificate chains, and verify TLS protocols in seconds.