TLS Handshake Error
TLS Handshake Error
Basic Flow
When you see “TLS handshake” followed by an “SSL alert” (or “TLS Alert”) in Wireshark or logs, it means the TLS handshake failed, and one peer (client or server) sent an alert message describing why the handshake could not continue.
Let’s go step by step �
TLS Handshake + SSL Alert Overview
A TLS handshake is the negotiation phase where the client and server agree on:
Protocol version (e.g., TLS 1.2 / 1.3)
Cipher suite
Certificates and authentication
Session keys
If anything goes wrong in this process, the peer sends a TLS Alert (protocol content type 21) to indicate the failure.
What You’ll See in Wireshark
Example:
Frame 12: Client Hello
Frame 13: Server Hello
Frame 14: Certificate
Frame 15: Server Key Exchange
Frame 16: Server Hello Done
Frame 17: Client Key Exchange
Frame 18: Change Cipher Spec
Frame 19: Encrypted Handshake Message
Frame 20: Alert (Level: Fatal, Description: Handshake Failure)
This means:
The handshake proceeded until frame 19.
Then one side sent a fatal alert, ending the handshake.
Common TLS Alert Descriptions During Handshake
Description |
Code |
Meaning / Typical |
handshake_failure |
40 |
No common cipher suite or version mismatch |
protocol_version |
70 |
TLS version not supported by peer |
bad_certificate |
42 |
Certificate verification failed (expired, wrong CN, etc.) |
unknown_ca |
48 |
Issuer not trusted |
certificate_required |
115 |
Server required a client certificate but didn’t get one |
illegal_parameter |
47 |
Inconsistent or invalid parameter (e.g. signature_algorithms) |
decode_error |
50 |
Malformed handshake message |
decrypt_error |
51 |
Signature or key exchange validation failed |
internal_error |
80 |
Internal failure in TLS library |
inappropriate_fallback |
86 |
Client tried to downgrade to lower TLS version |
unsupported_extension |
110 |
Extension not recognized by server |
unrecognized_name |
112 |
SNI hostname not accepted |
no_application_protocol |
120 |
ALPN negotiation failed (e.g., HTTP/2 vs HTTP/1.1 mismatch) |
Encrypted Alerts in Handshake (TLS 1.3)
In TLS 1.3, after the initial “ServerHello”, all handshake messages are encrypted — including alerts.
So Wireshark will show only:
Alert (Level: Fatal, Description: Encrypted Alert)
That’s normal: TLS 1.3 hides the actual reason for privacy.
To know the real reason, you must:
Enable key logging (SSLKEYLOGFILE) to decrypt the session, or
Check the server/client application logs.
Common tls.alert_message.desc Values
Value Name Meaning / Typical Cause
0 close_notify Session is closed cleanly (normal).
10 unexpected_message Wrong message type received (e.g., server got “application_data” instead of “ClientHello”).
20 bad_record_mac Record integrity check (MAC) failed — often data corruption or decryption error.
21 decryption_failed_RESERVED Deprecated.
22 record_overflow Record length too long.
30 decompression_failure Problem decompressing data (if compression used).
40 handshake_failure Handshake negotiation failed (no compatible cipher, version, etc.).
41 no_certificate_RESERVED Old/deprecated (TLS 1.0).
42 bad_certificate Certificate failed verification (expired, revoked, wrong host, etc.).
43 unsupported_certificate Certificate type not supported.
44 certificate_revoked Certificate revoked.
45 certificate_expired Certificate expired.
46 certificate_unknown Certificate problem not otherwise specified.
47 illegal_parameter Invalid parameter in handshake (e.g., wrong key exchange data).
48 unknown_ca Certificate authority not recognized.
49 access_denied Access denied by policy.
50 decode_error Could not parse a message correctly.
51 decrypt_error Cryptographic operation failed (bad signature, etc.).
70 protocol_version Unsupported TLS version.
71 insufficient_security Negotiated ciphers too weak for policy.
80 internal_error Internal error in peer’s TLS stack.
86 inappropriate_fallback Client tried lower TLS version fallback (e.g., TLS1.2 instead of 1.3).
90 user_canceled User canceled handshake.
109 missing_extension Missing required extension (e.g., SNI, signature_algorithms).
110 unsupported_extension Received an unknown or unexpected extension.
112 unrecognized_name SNI (Server Name Indication) mismatch.
113 bad_certificate_status_response Problem with OCSP response.
114 unknown_psk_identity PSK identity not found.
115 certificate_required Peer expected certificate but didn’t receive one.
120 no_application_protocol ALPN (e.g., HTTP/2 vs HTTP/1.1) mismatch.