TLS Handshake Failure Troubleshooting Guide: Read the Alert, Find the Mismatch, Fix It

A TLS handshake failure tells you that client and server could not agree on how to talk securely, but the message most tools print, such as "handshake failure" or curl error 35, hides which of a dozen mismatches caused it. The real cause is usually one of a few things: no common protocol version, no common cipher suite or signature algorithm, a missing or wrong SNI name, a client certificate the server required and did not get, an ALPN mismatch, or something in the path that is not speaking TLS at all. This guide maps the alerts and error strings to those causes, shows how to isolate each one with openssl s_client, packet captures and server logs, and gives the fix for each without lowering the security baseline. It is for platform, network and application engineers and for security teams who get the ticket after a hardening change. Error strings were checked against the OpenSSL, Go, OpenJDK, curl and Chromium sources on 11 November 2026.

Key takeaways

• Find out who sent the alert. "Received" alert means the other side rejected you; a locally generated failure means your own stack refused. The fix is on opposite ends.
• The alert number narrows the cause. 40 handshake_failure, 70 protocol_version, 112 unrecognized_name, 116 certificate_required, 120 no_application_protocol and 48 unknown_ca each point to a different mismatch.
• Reproduce with openssl s_client, one variable at a time. Force a version, a cipher list, a server name or a client certificate and see which change makes the handshake succeed.
• Most failures follow a change. Disabling TLS 1.0 and 1.1, a new load balancer security policy, a certificate with a different key type or a new proxy explains most incidents. Check the change log first.
• Never fix by downgrading globally. Re-enabling retired protocols or weak suites for one legacy client exposes every client. Isolate the legacy client behind its own listener and plan its upgrade.

How the handshake breaks

In TLS 1.3 (RFC 8446) the client sends a ClientHello listing supported versions, cipher suites, key exchange groups, signature algorithms, the server name (SNI) and application protocols (ALPN). The server picks one of each, sends its certificate and proves possession of the key, and may request a client certificate. Any step can fail, and RFC 8446 says a server that cannot negotiate a supported parameter set must abort with a handshake_failure or insufficient_security alert. RFC 8446 defines handshake_failure as indicating "that the sender was unable to negotiate an acceptable set of security parameters given the options available". The How TLS Works Guide explains the handshake itself; this guide assumes you know it and focuses on the failure.

Alert and error reference

Alert numbers are from RFC 8446 and the OpenSSL and Go source. Strings are quoted from current OpenSSL (crypto/err/openssl.txt), Go (crypto/tls) and OpenJDK source.

Locally generated failures read differently. On a Go server, tls: no cipher suite supported by both client and server, tls: client offered only unsupported versions and tls: client didn't provide a certificate name the cause directly. OpenSSL reports no shared cipher, unsupported protocol, no protocols available, no suitable signature algorithm or peer did not return a certificate. Java prints Received fatal alert: followed by the alert name when the peer sent it, and No appropriate protocol (protocol is disabled or cipher suites are inappropriate) when its own configuration leaves nothing to offer. curl returns exit code 35 (CURLE_SSL_CONNECT_ERROR), whose documentation advises reading the error buffer because it "pinpoints the problem slightly more".

Likely causes, most to least common

1. Protocol version mismatch: a server or load balancer policy now requires TLS 1.2 or 1.3, and an old client, library or embedded device only offers TLS 1.0 or 1.1, or the reverse with a client pinned to TLS 1.3 against an old server. Chromium reports ERR_SSL_VERSION_OR_CIPHER_MISMATCH, which its source describes as client and server not supporting a common protocol version or cipher suite.
2. Cipher suite or signature algorithm mismatch: the client offers only suites the server has removed (CBC or RSA key exchange suites), or the certificate key type does not fit what the client accepts, for example an ECDSA certificate presented to a client that offers only RSA suites in TLS 1.2.
3. Client certificate required but not sent: mTLS endpoints reject callers that send no certificate, an expired one or one from an untrusted issuer. In TLS 1.3 this is alert 116; in TLS 1.2 it is usually 40. Chromium shows ERR_BAD_SSL_CLIENT_AUTH_CERT.
4. SNI problems: the client connects by IP address or an internal alias and sends no SNI or the wrong name, so the server returns a default certificate or the unrecognized_name alert. Old clients that do not send SNI fail on shared listeners.
5. Something in the path is not TLS: connecting with TLS to a plain HTTP port, or through a proxy that answers in plain text, produces OpenSSL's wrong version number or Go's first record does not look like a TLS handshake. A connection cut by a firewall or middlebox shows as unexpected eof while reading.
6. ALPN mismatch: HTTP/2 or gRPC clients that require h2 fail against a server or proxy offering only http/1.1.
7. TLS inspection: a proxy re-terminates TLS with its own policy and may not support the version, group or client certificate flow the destination needs. See the TLS Inspection Guide.

How to diagnose it

1. Record the change history: list TLS policy changes, certificate replacements, load balancer or proxy updates and client library upgrades in the last few days on both sides.
2. Get both sides' view: collect the client error and the server or load balancer log for the same timestamp. On Windows, Schannel errors go to the System event log, and the EventLogging DWORD under HKLM\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL sets the level (7 logs errors, warnings, informational and success events; Microsoft notes a reboot is required after changing it).
3. Baseline with openssl s_client: openssl s_client -connect host:443 -servername host -brief. -brief prints the negotiated version, cipher and peer certificate summary when it works.
4. Vary one parameter at a time: force versions with -tls1_2 or -tls1_3; restrict TLS 1.2 ciphers with -cipher and TLS 1.3 suites with -ciphersuites; set -sigalgs or -groups; test SNI with a different -servername or with -noservername; offer ALPN with -alpn h2,http/1.1; present a client certificate with -cert and -key. The variant that succeeds identifies the mismatch.
5. Test from the client's network position: repeat from the failing host or pod. A proxy, NAT gateway or service mesh sidecar can mean the client is not talking to the server you tested.
6. Capture the ClientHello: a packet capture filtered on the TLS handshake shows exactly which versions, suites, groups, SNI and ALPN the client offered and which alert came back, and from which side. For Java clients, -Djavax.net.debug=ssl:handshake prints each handshake message.
7. For protocol-switching services: mail, LDAP and database protocols often start in plain text and upgrade; test with openssl s_client -starttls smtp (or ldap, postgres, mysql and others) rather than direct TLS.

The OpenSSL for Security Teams guide covers these commands in more detail.

Fixes by cause

When a server certificate is not trusted, the failure is usually reported as a verification error rather than a handshake alert; the x509 Certificate Signed by Unknown Authority Troubleshooting Guide covers that case, and the Expired Certificate Outage Troubleshooting Guide covers expiry.

Testing and rollback for TLS policy changes

1. Measure before you tighten: log the negotiated version and cipher per connection for at least a full business cycle, and list clients still using what you plan to remove.
2. Stage the change: apply the new policy to a test listener or a canary node first, and run each known client type against it.
3. Roll out in rings: internal endpoints, then partner endpoints with notice, then public endpoints.
4. Keep the old policy definition ready: rollback should be a one-step policy reassignment on the listener, not a rebuild.
5. Track exceptions: every legacy listener created during rollout gets an owner and a removal date.

The target baseline is set out in the TLS Server Configuration Baseline Guide. Downgrade risks, including why fallback to older versions is dangerous, are covered in the Historic TLS Attacks Guide.

Decision guidance

• Legacy device you cannot upgrade: terminate its TLS on a separate, tightly scoped listener or gateway, restrict who can reach it and record the risk. Do not let one device set the policy for everyone.
• Partner integration failing after your hardening: share the exact policy (versions, suites, groups, certificate key type) and a test endpoint; most partners can fix a client configuration quickly when they know what to change.
• mTLS service-to-service failures: treat them as identity problems first: which client certificate was sent, who issued it, and whether the server trusts that issuer.
• Small organisation: use the defaults of a maintained server or managed load balancer policy rather than hand-written cipher lists; most handshake failures in small estates come from copied old configurations.
• Large organisation: publish named TLS profiles centrally and log the negotiated parameters everywhere, so the next policy change can be checked against real traffic.

Where identity fits

The handshake is where a workload proves its identity. In mTLS, failures with alerts 42, 48 and 116 are almost always about a client identity: a certificate not sent, expired, or issued by a CA the server does not trust. Agents and service accounts that call APIs over mTLS inherit the same failure modes, and the temptation to "just disable client auth" removes the workload's identity check. See the mTLS Guide and the Machine Identity, PKI and Certificate Lifecycle Guide.

Detection and measurement

• Handshake failure rate: per listener, from load balancer, proxy or web server logs; alert on a step change after any deployment.
• Negotiated parameters: share of connections by TLS version and cipher, so you know who breaks before you tighten.
• Alert breakdown: counts by alert type (40, 42, 48, 70, 112, 116, 120) point to the cause class without packet captures.
• Downgrade attempts: unexpected connections offering retired versions can indicate old software or a downgrade attempt (MITRE ATT&CK T1689 Downgrade Attack).
• Metrics: handshake failure rate per listener; percentage of traffic on TLS 1.3; number of legacy exception listeners and their age; mean time to identify the cause of a handshake incident; mTLS client certificates expiring in the next 30 days.

Framework mapping

Common failure patterns

• Testing from the wrong place: the handshake works from an engineer's laptop and fails from the pod, because the pod goes through a proxy or sidecar with a different policy.
• Testing by IP address: s_client without the right -servername receives a default certificate or an unrecognized_name alert and sends the investigation in the wrong direction.
• Global downgrade: TLS 1.0 re-enabled on the main listener for one client, then never removed.
• Certificate swap breaks old clients: moving from RSA to ECDSA without checking that every client supports it.
• Client auth disabled to restore service: an mTLS failure "fixed" by turning off client certificate checks, leaving the API open to any caller who can reach it.

Practitioner checklist

• Establish which side sent the alert and record its name and number.
• Check recent TLS policy, certificate, proxy and client library changes on both sides.
• Reproduce with openssl s_client -servername from the failing client's network position.
• Vary version, ciphers, groups, SNI, ALPN and client certificate one at a time until the handshake succeeds.
• Capture the ClientHello when logs are not conclusive.
• Fix the client or the specific listener; never downgrade the shared baseline.
• Give every legacy exception an owner and an end date.
• Log negotiated version and cipher per connection before the next hardening change.

Standards and references

• IETF: RFC 8446 The Transport Layer Security (TLS) Protocol Version 1.3
• OpenSSL: openssl-s_client
• curl: libcurl error codes
• Go: crypto/tls alert definitions
• OpenSSL: error reason strings (crypto/err/openssl.txt)
• Microsoft Learn: TLS registry settings
• MITRE ATT&CK: Downgrade Attack

Related NHI Mgmt Group resources: How TLS Works Guide · TLS Server Configuration Baseline Guide · mTLS Guide · x509 Certificate Signed by Unknown Authority Troubleshooting Guide