About the TLS Handshake Failures
A TLS failure produces an error message from the client, and client error messages are famously unhelpful about which side is actually at fault. The handshake has a small number of failure points — protocol version, cipher suite, certificate chain, hostname, and clock — and each produces a distinguishable symptom once you know what to look for.
This playbook works through them in the order the handshake does, so the first thing that can fail is checked first. That ordering matters: a version mismatch and an untrusted chain are entirely different problems, and diagnosing them out of order wastes the early minutes of an outage.
The most common production cause by a wide margin is an incomplete certificate chain. The server sends its leaf certificate but omits the intermediate, and the failure is intermittent by client — browsers often paper over it by fetching the missing intermediate, while command-line tools and language runtimes do not.
Frequently asked questions
How do I tell whether the problem is the certificate or the chain?
Fetch the certificate the server actually presents and count what comes back. A server sending only its leaf has an incomplete chain even if the certificate itself is perfectly valid. The tell is that browsers succeed while curl or a language HTTP client fails, because browsers cache and fetch intermediates that other clients will not.
What causes a handshake failure with no useful error?
Usually no overlap in what the two sides will accept — either no shared protocol version or no shared cipher suite. This surfaces after a server hardening change that disabled older versions, or when an old client meets a modern configuration. Test by explicitly requesting each protocol version in turn to find where support stops.
Why does the certificate work for one hostname but not another?
Hostname validation reads the Subject Alternative Name extension only; the Common Name has been ignored for this purpose by current clients for years. A certificate covering the apex domain does not cover a subdomain unless it is listed, and a wildcard covers exactly one label — it matches one level down and not two.
Can clock skew break TLS?
Yes, and it produces a confusingly worded error about the certificate not being valid yet or having expired. A client whose clock is days off rejects a perfectly good certificate. It is worth checking early on embedded devices, freshly built virtual machines, and containers on a host with no working time synchronisation.
What does SNI have to do with handshake failures?
Server Name Indication tells the server which hostname is being requested so it can select the right certificate, and it is sent before encryption begins. A client that omits it — some older libraries, and requests made directly to an IP address — gets whatever default certificate the server holds, which is usually for the wrong hostname and fails validation.
Need this managed for you, not just automated?
We're also a hands-on DevOps consultancy — Kubernetes, CI/CD, and cloud infrastructure.