curl stops with 'sslv3 alert handshake failure' on an HTTPS request
curl: (35) error:14094410:SSL routines:ssl3_read_bytes:sslv3 alert handshake failureShort 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.
Fix it fast
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/2Match what you see, then jump to its fix
- 1
The 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
The 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
The 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
- 1
What does the error look like?
curl: (35) error:14094410:SSL routines:ssl3_read_bytes:sslv3 alert handshake failureerror: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.com2Fix
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
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
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
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 fixServers
Ansible hangs, then times out waiting for the sudo prompt
a playbook using become seems to hang
Ansible ran sudo on the target and never saw the answer it expected.
3 causes, each with a fixServers
Apache on Ubuntu returns 404 Not Found for my site
The requested URL was not found on this server.
On Ubuntu a 404 from Apache usually means the request maps to a path that has no file.
3 causes, each with a fixServers
Apache returns 504 Gateway Timeout when PHP takes too long
Quick requests work, slow ones end in a 504 after a fixed wait
A 504 from Apache means the backend did not answer within the proxy timeout.
2 causes, each with a fixServers
Apache logs SIGWINCH and exits on its own
the httpd container stops although nothing crashed
SIGWINCH is Apache's graceful-stop signal.
2 causes, each with a fixServers
Apache warns that a ${VAR} config variable is not defined
${VAR} left unchanged in the configuration, with a warning in the error log
Apache expands ${VAR} from Define or from the shell environment that exists when the server starts.
3 causes, each with a fix