SSL_ERROR_HANDSHAKE_FAILURE_ALERT in Firefox: causes and fixes

SSL_ERROR_HANDSHAKE_FAILURE_ALERT means the server ended the TLS handshake with a handshake_failure alert. Firefox shows "Secure Connection Failed" with "An error occurred during a connection to example.com. SSL peer was unable to negotiate an acceptable set of security parameters." Usually the server wanted a client certificate Firefox did not send, or accepts only cipher suites Firefox no longer offers.

What the alert means

The server rejected the handshake parameters Firefox offered and did not say which one. TLS servers report fatal problems with numbered alerts. The TLS 1.3 specification, RFC 9846, defines handshake_failure (40) as an indication that the sender "was unable to negotiate an acceptable set of security parameters given the options available". NSS, Firefox's TLS library, maps that alert to SSL_ERROR_HANDSHAKE_FAILURE_ALERT.

Chrome reports the same server behaviour as ERR_SSL_VERSION_OR_CIPHER_MISMATCH, or as ERR_BAD_SSL_CLIENT_AUTH_CERT when a client certificate is involved.

Common causes, most frequent first

1. The server requires a client certificate

Corporate portals, government services, banking back offices and VPN gateways often require mutual TLS. If Firefox sends no certificate, an OpenSSL-based server configured to require one aborts. In OpenSSL, the TLS 1.3 alert certificate_required is translated to handshake_failure on TLS 1.2 connections, so on TLS 1.2 you get exactly this error.

Confirm by checking whether the server asks for a certificate:

openssl s_client -connect example.com:443 -servername example.com -tls1_2 </dev/null 2>/dev/null \
  | sed -n '/Acceptable client certificate CA names/,/Requested Signature/p'

A list of CA names means the server requests client certificates. Apache does this with SSLVerifyClient require.

On the Firefox side, Firefox 90 and later look for client certificates in the Windows and macOS certificate stores automatically. Certificates on smart cards or USB tokens need the vendor's PKCS#11 module loaded under Settings > Privacy & Security > Security Devices. An expired personal certificate is treated as no certificate.

2. The server accepts only legacy cipher suites

Old appliances, embedded web interfaces and unpatched servers may accept only suites that current Firefox no longer offers. Compare what the server accepts with what modern clients send:

openssl s_client -connect example.com:443 -servername example.com -tls1_2 -brief </dev/null
nmap --script ssl-enum-ciphers -p 443 example.com

If only old CBC or 3DES suites appear, the server must be updated. Look up any suite with the cipher suite lookup.

3. Firefox TLS preferences were changed

Hardening guides and some extensions change security.ssl3.* or security.tls.version.* in about:config. If you disabled the suites a server needs, the server answers with this alert. Test in a fresh Firefox profile (about:profiles > Create a New Profile). If it works there, reset the changed preferences.

4. Security software or a proxy in the middle

Antivirus HTTPS scanning and corporate proxies terminate TLS themselves. If their own outbound configuration is outdated, the upstream server rejects them and the alert is passed on to Firefox. Turning off HTTPS scanning briefly, or trying another network, shows whether this is the cause. See antivirus HTTPS scanning.

5. Hostname not configured on the TLS terminator

Some load balancers and CDNs abort with a generic failure alert when they have no certificate for the requested hostname instead of sending unrecognized_name. Run the openssl s_client command with and without -servername and compare.

How to fix it

Users install or select the client certificate the site requires; administrators enable modern cipher suites or fix the client-certificate setup.

Users of a site that needs a personal certificate: 1. Update Firefox to the current release. 2. Install the certificate in the operating system store, or import the .p12/.pfx file under Settings > Privacy & Security > Certificates > View Certificates > Your Certificates. 3. For smart cards, load the PKCS#11 module from the card vendor under Security Devices. 4. Reload the page and pick the certificate when Firefox asks.

Server administrators: - Enable TLS 1.2 and 1.3 with ECDHE and AES-GCM or CHACHA20 suites; the TLS config generator outputs a tested block. - If client certificates are optional for some users, use SSLVerifyClient optional in Apache or ssl_verify_client optional; in Nginx and handle missing certificates in the application, which gives users a readable error page instead of a broken handshake. - Make sure every hostname has a certificate on every TLS terminator.

How to verify the fix

1. openssl s_client -connect example.com:443 -servername example.com -brief completes and prints the protocol and cipher.
2. For mutual TLS, test with the client certificate: openssl s_client -connect example.com:443 -servername example.com -cert client.pem -key client.key -brief.
3. Load the site in Firefox; the SSL checker confirms the server side looks normal from outside.