How to troubleshoot TLS handshake issues [Updated]

If you’ve encountered an error messaging saying “TSL Handshake Failed,” and you’re confused about what to do, you’re not alone. TLS handshake failed is a common error. While it can be a frustrating experience, there are ways to troubleshoot TLS handshake issues and solve them.

TLS handshake issues

In this post, you’ll learn what the TLS Handshake Failed error is and why it occurs. Then you’ll learn how to troubleshoot TLS handshake issues.

Let’s get started!

Understanding TLS/SSL

You need to make your website secure so as to establish secure connections between two servers. To do this, you’ll need to install a Secure Sockets Layer (SSL) certificate - SSL encryption and security protocol - on your site. This will enable your site to use HTTPS to ensure secure connections.

Unfortunately, sometimes things don’t go as planned, and you may encounter a problem when making a connection between your site’s server and a visitor’s browser. The problem can occur as a ‘TLS Handshake Failed’ error or any other issue.

Transport Layer Security (TLS) and Secure Sockets Layer (SSL) are security protocols that provide website encryption and identification. They are used to authenticate data transfers between servers, applications, systems such as browsers, and users.

Simply put, you need TLS/SSL certificates to secure your website using HTTPS.

Understanding TLS/SSL handshake

A TLS handshake is a form of communication and agreement between two servers - your sites’ host and the client’s server. It is the first step in the process of establishing a clear HTTPS connection.

To authenticate and establish a connection, your site’s server and the client’s browser must shake hands, i.e., go through a series of checks (the handshake). This establishes the HTTPS connection parameters.

What does this mean?

The client (usually a browser) typically sends a request to establish a secure connection to the site’s server. The server then sends a public key (protocol) to your device and ensures to check that key against a pre-prepared list of protocols/certificates. The device then generates a key and uses the server’s key to encrypt it.

If this back and forth communication doesn’t yield a positive result, i.e., if the SSL handshake fails between the server and the client, HTTPS won’t generate a secure connection, which will result in a TLS/SSL handshake failure. This error can show in two forms;

HTTP/1.1 503 Service Unavailable
Received fatal alert: handshake_failure (Error 525)

TLS error 525

Note: You’ll see these error messages following an API call where a TLS handshake failure occurs.

What causes TLS handshake issues

Generally, Error 525 or Error 503 usually means that there’s been a failed TLS handshake. Some of the causes of the failure can include;

On the server-side, the error causes include;

Protocol mismatch: The server doesn’t support the protocol that the client used.
Incorrect certificate: The hostname of the client’s URL does not match the hostname in the certificate stored at the server end, or the certificate is incomplete or invalid, or the certificate is incorrect or expired
Cipher suite mismatch: The server does not support the cipher suite that the client used.
SNI enabled server: when the back end SNI (Server Name Identification) is enabled, but the client-server cannot communicate with the SNI servers.

On the client’s side, the causes can include;

If the connection is being intercepted by a third party.
If the client’s device has a wrong date or time.
If the client is experiencing an error with the browser configuration.

How to troubleshoot TLS handshake issues

There are several potential causes of the “TLS Handshake issues.” You can use the following solutions to troubleshoot these issues;

Method #1: Update your system’s date and time

A wrong date or time setting is one of the key causes of TLS handshake issues. Because the system time helps to test whether the certificate is valid or expired, a mismatch between your device’s time or date and that of the server can make the certificates look expired.

Fix the time and date by setting it to automatic, then visit the site again and see if the TLS handshake issue has been fixed.

Method #2: Fix your Browser’s configuration to match the Latest TLS Protocol Support

Your browser is the ‘man in the middle’, and it can affect how your device communicates with the server. Any browser misconfiguration can cause TLS issues.

To check if your browser is the problem, try to use another browser to access the site and see if you are encountering the same problem. If the problem is occurring in all sites, then it’s a system problem.

Perhaps there is a browser extension or security software on your device that is intercepting the TLS connections and causing the problematic TLS handshake. In a number of cases, a virus or malware on the system was involved.

To fix this issue:

You may need to disable the security software or browser extensions on your device, or,
Reset your browser.

Method #3: Check and Change TLS Protocols [in Windows]

Browser related problems can also be caused by protocol mismatch.

For instance, if the browser is only configured for a specific TLS value, e.g., TLS 1.0 or TLS 1.1, but the server only supports TLS 1.2, then there’s the communication between the two will lack a mutually-supported protocol. This inevitably leads to a TLS handshake failure.

To check this issue in your browser (Google Chrome):

Open Chrome browser
Go to Settings > Advanced
Scroll down open Systems > Open your computer’s proxy settings
On the new popup Windows select the Advanced tab.
In the advanced tab, under the Security section, see if the box next to Use TLS 1.2 is selected > check it if its not checked.
See if the boxes for SSL 2.0 and SSL 3.0 are checked > then uncheck them if so. Do the same for TLS 1.0 and TLS 1.1.
Click OK, then check to see if this process has resolved the handshake error.

Note: if you’re using Mac Os or Apple Safari, they don’t provide an option to disable or enable TLS/SSL protocols because TLS 1.2 is, by default, automatically enabled.

Method #4: Verify Your Server Configuration [to Support SNI]

Server name indication (SNI) configuration is one of the key causes of TLS issues. For the server to function properly, the SNI enables it to securely host several TLS certificates/protocols for one IP address.

On a server, each website has its own certificate. So, if the server isn’t SNI-enabled, there is a high likelihood of a TLS handshake failure because the server may fail to recognize the present certificate.

To check and see whether the site requires SNI, you can use the Qualys’ SSL Server Test. you’ll only need to input your site’s domain name, then click Submit and wait for the test to generate results.

On the results page, locate the message that reads “This site works only in browsers with SNI support”:

verify SNI

Method #5: Check and ensure that Cipher Suites Match

A Cipher Suites mismatch is also a key cause of TLS handshake issues, especially TLS handshake failure. Cipher suites are just a set of algorithms, including those for bulk encryption, key exchange, and message authentication code, which are used to secure TLS/SSL network connections.

If the server’s cipher suites don’t match with or support those of Cloudflare, there is a higher likelihood of a “TLD Handshake Failed” error.

To check the Cipher Suites configuration, you'll again use the Qualys’ TLS Server Test. Again, just input your domain, then click Submit and wait for the report.

On the results page, check under the Cipher Suites section to locate the Cipher information.

Be keen on the status such as those written ‘Weak.’ You can then correct them by comparing them with your browser support.

check and ensure that cipher suites match

Finally

We believe these tips have been easy to follow and that you were able to resolve the TLS handshake issue you encountered. TLS is an extremely vast topic, and there may be other solutions available.

If you found this useful, you might like our email list. We share many new tips, tricks, troubleshooting, how-to guides, product comparisons, and many more help-centered articles every day. Short, elaborate, sweet, and practical!