Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

curl stops with 'sslv3 alert handshake failure' on an HTTPS request

Errorcurl: (35) error:14094410:SSL routines:ssl3_read_bytes:sslv3 alert handshake failure

Short answer

The server answered curl's TLS hello with a handshake_failure alert, so it refused to agree on something. Run curl with -v to see how far the handshake got. The usual causes are a server that demands a client certificate, or a TLS version or cipher list that curl and the server do not share.

  • Applies to curl 8.x, OpenSSL 3.0, Ubuntu 24.04
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Repeat the request with verbose output and read the lines before the error. They show the TLS version curl offered and whether the server asked for a certificate.

    curl -v https://api.example.com/
  2. 2Match what you see, then jump to its fix

    1. 1The server is an API or gateway that is documented to need mutual TLS, and the alert arrives although curl sent no client certificate.The server requires a client certificate and curl sent noneFix
    2. 2The verbose output shows the client hello, and the alert arrives at once. The server is old (TLS 1.0 or 1.1 only), or it is strict and accepts TLS 1.3 only.curl and the server share no TLS versionFix
    3. 3The alert appears even with a TLS version the server supports, and a custom cipher list is set in your command or config.The server accepts none of the cipher suites curl offersFix

What does the error look like?

  • curl: (35) error:14094410:SSL routines:ssl3_read_bytes:sslv3 alert handshake failure
  • error:14094410:SSL routines:ssl3_read_bytes:sslv3 alert handshake failure

Cause 1 of 3

The server requires a client certificate and curl sent none

1Check

Ask the server's owner or its documentation whether mutual TLS is required. openssl s_client takes -cert and -key too, so you can repeat the handshake with and without a certificate.

openssl s_client -connect api.example.com:443 -servername api.example.com

2Fix

Pass the client certificate with --cert and its private key with --key. A key stored in the same file as the certificate needs no --key.

curl --cert client.crt --key client.key https://api.example.com/

3Verify

The request now returns an HTTP status line instead of the TLS error.

curl -sS -o /dev/null -w '%{http_code}\n' --cert client.crt --key client.key https://api.example.com/

Confirmed by curl.se

Did this fix it?

Cause 2 of 3

curl and the server share no TLS version

1Check

Force one version at a time and note which one completes the handshake. --tlsv1.2 asks for 1.2 or later, and --tls-max sets the highest version curl may use.

curl -v --tlsv1.2 --tls-max 1.2 https://api.example.com/
curl -v --tlsv1.3 https://api.example.com/

2Fix

Make the server accept TLS 1.2 or newer, since curl 8.16.0 asks for at least TLS 1.2 by default. Use a --tls-max value only as a short test to find out what the server supports.

curl -v --tlsv1.2 --tls-max 1.2 https://api.example.com/

3Verify

The handshake finishes and the verbose output shows the negotiated TLS version.

curl -sS -o /dev/null -w '%{http_code}\n' --tlsv1.2 https://api.example.com/

Confirmed by curl.se

Did this fix it?

Cause 3 of 3

The server accepts none of the cipher suites curl offers

1Check

Look for --ciphers or --tls13-ciphers in your command, in ~/.curlrc and in any wrapper script.

grep -n -i "cipher" ~/.curlrc; echo "$CURL_HOME"

2Fix

Remove the custom list so curl offers its default suites, or set a list that includes a suite the server supports. --ciphers sets the list for TLS 1.2 and older, and --tls13-ciphers sets it for TLS 1.3.

curl -v https://api.example.com/

3Verify

The request completes without the alert.

curl -sS -o /dev/null -w '%{http_code}\n' https://api.example.com/

Confirmed by curl.se

Did this fix it?

How do I stop it coming back?

  • Keep client certificates and keys in a known folder and pass them with --cert and --key in one saved script.
  • Do not leave --ciphers or --tls-max in .curlrc after a test.
  • Ask API providers which TLS versions they accept before you pin one in code.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Related fixes

Servers

dnf cannot install MySQL on Amazon Linux 2023

dnf cannot find a mysql-server package on Amazon Linux 2023

Amazon Linux 2023 documents MariaDB, not MySQL, as its database server, with packages named mariadb105 and mariadb105-server.

3 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.