What Is an SSL Handshake Failure? – Causes and Fixes
Learn what a TLS handshake failure means, which negotiation step failed, how to diagnose version and cipher mismatches, and how to fix each case.
A handshake failure means client and server could not agree on how to secure the connection. It happens before any HTTP request is sent, so no status code is ever produced.
1. What the Handshake Negotiates
- Protocol version — both sides must support a common TLS version.
- Cipher suite — a mutually acceptable set of algorithms.
- Server identity — the certificate and its chain.
- Optionally client identity — where mutual TLS is required.
A failure at any step aborts the connection.
2. Reading the Failure
| Message | Meaning |
|---|---|
| Protocol version alert | No shared TLS version |
| Handshake failure alert | No shared cipher suite, or a policy refusal |
| Unknown CA | The client does not trust the chain |
| Certificate required | The server expects a client certificate |
| Bad certificate | A client certificate was rejected |
| Unrecognised name | The requested hostname is not served here |
3. Diagnosing It
openssl s_client -connect example.com:443 -servername example.com </dev/null
openssl s_client -connect example.com:443 -tls1_2 </dev/null
Forcing a version identifies a version mismatch immediately. Omitting -servername reproduces what a client that does not send SNI experiences, which is a distinct and common failure on shared hosting.
4. Common Causes
- Old client, modern server. Servers dropping older TLS versions break legacy clients.
- Modern client, old server. Clients removing obsolete ciphers cannot negotiate with outdated servers.
- Missing SNI. A client that does not send the server name receives a default certificate or a refusal.
- Interception. Inspecting middleboxes substitute their own certificate; without its root trusted, the handshake fails.
- Mutual TLS. A client certificate is required and not presented.
- Cipher policy. Hardened configurations on either side leave no overlap.
5. Fixing It
- Update the client library and its TLS backend. Most version and cipher problems resolve here.
- Confirm SNI is sent. Every modern client does; very old ones may not.
- Trust the correct root where inspection or an internal authority is involved, rather than disabling verification.
- Review server cipher policy if legitimate clients cannot connect.
- Present the client certificate where mutual TLS is expected.
6. Handshakes as a Fingerprint
The handshake's composition — versions offered, cipher order, extensions — differs between browsers and HTTP libraries, and is stable enough to identify the client family.
That is why a request declaring a browser user agent over a library's handshake is contradictory, and why some sites refuse it. The observation is neutral: it is simply information the connection reveals before any header is read.
7. Real-World Examples
- A legacy device failing after a server disables older TLS versions.
- A corporate inspecting proxy breaking API clients while browsers are unaffected.
- A shared-hosting site returning the wrong certificate to a client that omits SNI.
- A mutual-TLS endpoint rejecting requests from a client that never loaded its certificate.
8. Summary
A TLS handshake failure means no agreement was reached on version, cipher, or identity, and it occurs before any HTTP exchange.
Forcing a specific version with a command-line client isolates the cause quickly. Fix by updating clients, trusting the correct roots, and reviewing cipher policy — never by disabling verification.