On this page 15 sections
- Read the error before changing anything
- Cause and fix at a glance
- Plain HTTP where TLS was expected: “wrong version number”
- The certificate is not trusted
- A proxy is intercepting TLS
- The name does not match, or no name was sent
- No TLS version in common
- No cipher suite in common
- Expired certificate or a wrong clock
- The server wants a client certificate
- The proxy refused the CONNECT
- The tunnel opened, then the far end hung up
- Cloudflare 525, 526 and 1013
- A triage script that names the broken layer
- How these errors were produced
“SSL handshake failed” is the umbrella phrase. Your client prints something more specific, and that text tells you which side gave up and why. Below is one test server that accepts exactly one TLS 1.2 cipher suite, ECDHE-ECDSA-AES256-CCM, and what six clients on the same Mac said when they connected to it:
# curl 8.23.0, OpenSSL 4.0.3
curl: (35) TLS connect error: error:0A000410:SSL routines::tls alert handshake failure
# curl 8.7.1, LibreSSL 3.3.6 (the curl that ships with macOS)
curl: (35) LibreSSL/3.3.6: error:1404B410:SSL routines:ST_CONNECT:sslv3 alert handshake failure
# Python 3.12.13, requests 2.34.2, OpenSSL 3.6.5
requests.exceptions.SSLError: HTTPSConnectionPool(host='localhost', port=18453): Max retries exceeded with url: / (Caused by SSLError(SSLError(1, '[SSL: SSLV3_ALERT_HANDSHAKE_FAILURE] ssl/tls alert handshake failure (_ssl.c:1010)')))
# Python 3.9.6, requests 2.32.3, LibreSSL 2.8.3 (the macOS system Python)
... (Caused by SSLError(SSLError(1, '[SSL: SSLV3_ALERT_HANDSHAKE_FAILURE] sslv3 alert handshake failure (_ssl.c:1129)')))
# Chrome 155.0.8059.85, headless
net::ERR_SSL_VERSION_OR_CIPHER_MISMATCH
# Node 24.2.0, OpenSSL 3.6.5: no error; tls.connect() negotiated
TLSv1.2 ECDHE-ECDSA-AES256-CCM
Five refusals, one success, and four spellings of the same event. The server sent TLS alert 40, handshake_failure, which RFC 8446 section 6 defines. OpenSSL 4.0.3 calls it “tls alert handshake failure”. OpenSSL 3.6.5 says “ssl/tls alert handshake failure”. LibreSSL still says “sslv3”, a name inherited from a protocol long retired. Node got through because it offered that CCM suite and the others did not.
So an SSL or TLS handshake failure means one thing at the protocol level: before a single byte of HTTP was exchanged, one side sent an alert or hung up, and the connection was dropped. The useful question is which side, and the message nearly always says. Every client error message on this page was produced on purpose against local servers and proxies; the method is at the end.
Read the error before changing anything
Handshake errors come in four shapes. Each one points at a different machine.
- The word “alert”.
tlsv1 alert protocol version,tls alert handshake failure,tlsv13 alert certificate required,tlsv1 unrecognized name. The other side refused and told you why. Node appends the alert number, which maps straight onto RFC 8446: 40 is handshake_failure, 70 protocol_version, 112 unrecognized_name, 116 certificate_required. - “verify failed” or “certificate problem”. curl exit 60 (libcurl: “The remote server’s SSL certificate or SSH fingerprint was deemed not OK”), Python
CERTIFICATE_VERIFY_FAILED, ChromeERR_CERT_*. The handshake itself worked. Your own client rejected the certificate it was shown. - “unexpected eof”, “SSL_ERROR_SYSCALL”, “connection reset” or “socket disconnected”. Somebody closed the TCP connection without sending an alert. A TLS stack that refuses you normally says why, so a bare close points at something in the path, or at a server that decided not to talk to you at all.
- “CONNECT tunnel failed” or “Tunnel connection failed”. No TLS happened. Your proxy answered the CONNECT request with something other than 200, and the client reports it beside the TLS errors because that is where it was in its code.
Cause and fix at a glance
The sections below follow this order, which is roughly the order worth checking: the first rows take one command to confirm or rule out. The middle column is what curl 8.23.0 printed in our tests.
| Cause | What curl 8.23.0 prints | Confirm with | Fix |
|---|---|---|---|
Plain HTTP where TLS was expected, including an https:// proxy URL for an HTTP proxy |
(35) ... wrong version number |
curl http://host:port/ gets an answer |
Right port; http:// in the proxy URL |
| Certificate not trusted: self-signed, missing intermediate, no CA bundle | (60) ... self-signed certificate (18) or unable to get local issuer certificate (20) |
openssl s_client -showcerts |
Serve the full chain; install or point to the CA bundle |
| A proxy intercepting TLS | (60) ... self-signed certificate in certificate chain (19) |
Compare the issuer with and without the proxy | Trust the interception CA, or exempt the host |
| Name on the certificate does not match | (60) SSL: no alternative certificate subject name matches target hostname |
openssl x509 -noout -ext subjectAltName |
Connect by a name the certificate covers |
| No SNI sent, usually because you connected by IP | (35) ... tlsv1 unrecognized name |
Repeat by hostname | Use the hostname; --resolve to pin the address |
| No TLS version in common | (35) ... tlsv1 alert protocol version |
openssl s_client -tls1_2, -tls1_3 |
Upgrade the server to TLS 1.2 or 1.3 |
| No cipher suite in common | (35) ... tls alert handshake failure |
openssl s_client -cipher ... |
Enable ECDHE with AES-GCM or ChaCha20 on the server |
| Expired certificate, or a wrong clock | (60) ... certificate has expired (10) |
openssl x509 -noout -dates, date -u |
Renew; fix the clock |
| Server requires a client certificate | (56) ... tlsv13 alert certificate required |
Repeat with --cert and --key |
Send the client certificate; exempt it from interception |
| Proxy refused the CONNECT | (7) CONNECT tunnel failed, response 407 (or 403, 503) |
-w '%{http_connect}' |
Credentials, allowed ports, or the proxy’s upstream |
| Tunnel opened, then the far end hung up | (35) ... unexpected eof while reading |
Proxy log shows a 200 tunnel; try another path | Depends on who closed it |
| Cloudflare 525 or 526 | An error page, not a client error | Cloudflare’s own documentation | Site owner fixes the origin |
Plain HTTP where TLS was expected: “wrong version number”
A TLS client sends a ClientHello and expects a TLS record back. If the port speaks plain HTTP, the server answers with something like HTTP/1.1 400 Bad Request. The client reads the first bytes of that as a TLS record header, finds a version field that makes no sense, and stops.
$ curl https://localhost:18449/ # port 18449 runs a plain HTTP server
curl: (35) TLS connect error: error:0A00010B:SSL routines::wrong version number
$ /usr/bin/curl https://localhost:18449/ # macOS curl 8.7.1, LibreSSL 3.3.6
curl: (35) LibreSSL/3.3.6: error:1404B42E:SSL routines:ST_CONNECT:tlsv1 alert protocol version
Watch the second line. LibreSSL reports the same mistake as a protocol version alert, which sends people off upgrading TLS settings that were never the problem. Python said [SSL: WRONG_VERSION_NUMBER] wrong version number, Node said error:0A00010B:SSL routines:tls_validate_record_header:wrong version number, and Chrome showed net::ERR_SSL_PROTOCOL_ERROR.
Through a proxy, the usual trigger is the scheme in the proxy URL. An ordinary HTTP proxy accepts plain HTTP on its port and carries HTTPS inside a CONNECT tunnel. Write https:// in front of the proxy address and the client tries to speak TLS to the proxy itself:
$ curl -x https://127.0.0.1:18460 https://localhost:18441/
curl: (35) TLS connect error: error:0A00010B:SSL routines::wrong version number
Squid logged that attempt as NONE_NONE/400 ... error:invalid-request: it received a ClientHello where it expected an HTTP request line. urllib3, under requests 2.34.2, recognises the pattern and says so outright: Unable to connect to proxy. Your proxy appears to only use HTTP and not HTTPS, try changing your proxy URL to be HTTP. httpx 0.28.1 gives only the bare [SSL: WRONG_VERSION_NUMBER].
The fix is http:// in the proxy URL, even when the target is HTTPS. The target’s TLS still runs end to end inside the tunnel. The curl proxy guide and the HTTPS_PROXY guide cover the scheme rules for each client. To confirm a port speaks HTTP, ask it in HTTP:
$ curl -sS -o /dev/null -w '%{http_code}\n' http://localhost:18449/
200
The reverse mistake exists too. Our Squid also ran a TLS listener, the kind used to encrypt the hop between client and proxy. Pointing http:// at it produced curl: (56) Recv failure: Connection reset by peer in both curl builds, and requests raised ConnectionResetError(54, 'Connection reset by peer').
The certificate is not trusted
These are failures of your client’s verification, not of the handshake itself. Three variants produced three different messages:
# self-signed leaf
curl: (60) SSL certificate OpenSSL verify result: self-signed certificate (18)
# server sends its leaf certificate but not the intermediate that signed it
curl: (60) SSL certificate OpenSSL verify result: unable to get local issuer certificate (20)
# the same two in Node 24.2.0
DEPTH_ZERO_SELF_SIGNED_CERT: self-signed certificate; if the root CA is installed locally, try running Node.js with --use-system-ca
UNABLE_TO_VERIFY_LEAF_SIGNATURE: unable to verify the first certificate; if the root CA is installed locally, try running Node.js with --use-system-ca
A missing intermediate is the classic “works in my browser, fails in my script” case. Browsers can often fill the gap from intermediates they have cached or fetched. Python’s ssl module does not: the request to add that behaviour, CPython issue 62817, “AIA chasing for missing intermediate certificates on TLS connections”, is still open. The server has to send the chain.
To see what a server sends, list the chain. Here only depth 0 arrives, issued by an intermediate the client has never seen (output trimmed to the relevant lines):
$ openssl s_client -connect localhost:18448 -servername localhost -CAfile root.pem -showcerts </dev/null
verify error:num=20:unable to get local issuer certificate
verify error:num=21:unable to verify the first certificate
0 s:CN=localhost
i:CN=PW Test Intermediate CA
Verify return code: 21 (unable to verify the first certificate)
On the server, configure the full chain file, leaf first and intermediates after it, rather than the leaf alone. On the client, a “local issuer” error inside a slim container image can mean no CA bundle is installed at all. If the CA is private, point the client at it rather than switching verification off. Each of these was tested here and returned 200:
curl --cacert /path/ca.pem https://host/
REQUESTS_CA_BUNDLE=/path/ca.pem python3 app.py # requests
SSL_CERT_FILE=/path/ca.pem python3 app.py # httpx
NODE_EXTRA_CA_CERTS=/path/ca.pem node app.js
One difference matters. REQUESTS_CA_BUNDLE, SSL_CERT_FILE and --cacert point the client at that file in place of its default bundle, so a file holding only your private CA will break every public site. Concatenate it onto the system bundle. Node’s documentation says NODE_EXTRA_CA_CERTS extends the built-in roots instead.
curl -k, verify=False and NODE_TLS_REJECT_UNAUTHORIZED=0 make the error go away by accepting any certificate from anyone, including whoever sits between you and the server. Use them to confirm a diagnosis for one request, never as the fix.
A proxy is intercepting TLS
Corporate gateways, antivirus products and debugging proxies can terminate your TLS session, inspect it, and open a second one to the real site. To do that they present a certificate for the site that they minted themselves, signed by their own CA. We ran Squid 6.13 with ssl_bump to reproduce it:
$ curl --cacert root.pem -x http://127.0.0.1:18462 https://localhost:18441/
curl: (60) SSL certificate OpenSSL verify result: self-signed certificate in certificate chain (19)
Python said certificate verify failed: self-signed certificate in certificate chain, Node’s fetch gave the cause SELF_SIGNED_CERT_IN_CHAIN, and Chrome showed net::ERR_CERT_AUTHORITY_INVALID. The site was fine; its real certificate verified when the same request went through a non-intercepting proxy port. See TLS interception for how the mechanism works.
The diagnostic is the issuer. Ask for the chain through the proxy and compare it with what you get directly:
$ openssl s_client -proxy 127.0.0.1:18462 -connect localhost:18441 -servername localhost -CAfile root.pem -showcerts </dev/null
0 s:CN=localhost
i:CN=PW Test Intercept CA
1 s:CN=PW Test Intercept CA
i:CN=PW Test Intercept CA
Verify return code: 19 (self-signed certificate in certificate chain)
Direct, the issuer was CN=PW Test Intermediate CA. Through the proxy it became the interception CA. If your IT department installed that CA in the operating system’s store, the browser trusts it and a script that carries its own bundle does not; requests, for one, “uses certificates from the package certifi”. Add the interception CA to the client’s trust with the variables above, or ask for the destination to be excluded from inspection.
Two cases cannot be fixed by trusting the CA. Apps that pin a certificate or key will reject any substitute by design (see certificate pinning). Sites that require a client certificate also break, because the intercepting proxy, not your client, now holds the TLS session and it has no copy of your private key.
The name does not match, or no name was sent
A certificate that does not cover the hostname fails verification:
curl: (60) SSL: no alternative certificate subject name matches target hostname 'localhost'
[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: Hostname mismatch, certificate is not valid for 'localhost'. (_ssl.c:1010)
ERR_TLS_CERT_ALTNAME_INVALID: Hostname/IP does not match certificate's altnames: Host: localhost. is not in the cert's altnames: DNS:other.test
Node’s message is the most useful because it prints the names the certificate does cover. With OpenSSL, read the extension directly:
$ openssl x509 -in wrong.pem -noout -ext subjectAltName
X509v3 Subject Alternative Name:
DNS:other.test
The other name problem is quieter. Servers that host many sites on one address pick a certificate from the Server Name Indication extension in the ClientHello. RFC 6066 forbids IP literals in that field, so a client connecting to an IP address sends no name. We built a server that refuses a ClientHello without SNI:
$ curl --cacert root.pem -H "Host: localhost" https://127.0.0.1:18451/
curl: (35) TLS connect error: error:0A000458:SSL routines::tlsv1 unrecognized name
$ curl --cacert root.pem --resolve localhost:18451:127.0.0.1 https://localhost:18451/ -o /dev/null -w '%{http_code}\n'
200
Setting the Host header by hand does not set SNI; curl takes SNI from the URL. --resolve keeps the name in the URL, so SNI and Host agree, and only the address lookup changes. Chrome reported the refusal as net::ERR_SSL_UNRECOGNIZED_NAME_ALERT.
No TLS version in common
RFC 8996 says TLS 1.0 and 1.1 “MUST NOT be used”, and the OpenSSL 3.6.5 and 4.0.3 clients we tested refuse them by default. A server that speaks only TLS 1.0 fails with those clients, which is how it should be. What catches people out is that some old clients still get through:
$ curl --cacert root.pem https://localhost:18452/ # curl 8.23.0
curl: (35) TLS connect error: error:0A00042E:SSL routines::tlsv1 alert protocol version
$ /usr/bin/curl --cacert root.pem https://localhost:18452/ -o /dev/null -w '%{http_code}\n' # macOS curl 8.7.1
200
The macOS system curl negotiated TLS 1.0 with ECDHE-ECDSA-AES256-SHA. So a legacy endpoint can “work in curl on my laptop” and fail in a container running the same command. Python 3.12 with OpenSSL 3.6.5 raised TLSV1_ALERT_PROTOCOL_VERSION; Python 3.9.6 on LibreSSL 2.8.3 said [SSL: WRONG_SSL_VERSION] wrong ssl version; Node reported SSL alert number 70; Chrome showed net::ERR_SSL_VERSION_OR_CIPHER_MISMATCH.
Probe one version at a time to see what a server accepts:
$ openssl s_client -connect localhost:18452 -servername localhost -CAfile root.pem -brief </dev/null
80A1C5FB01000000:error:0A00042E:SSL routines:ssl3_read_bytes:tlsv1 alert protocol version:ssl/record/rec_layer_s3.c:923:SSL alert number 70
$ openssl s_client -connect localhost:18441 -servername localhost -CAfile root.pem -brief </dev/null # trimmed
CONNECTION ESTABLISHED
Protocol version: TLSv1.3
Ciphersuite: TLS_AES_256_GCM_SHA384
Verification: OK
Negotiated TLS1.3 group: X25519MLKEM768
Add -tls1_2 or -tls1_3 to pin the version. The fix belongs on the server. Lowering a client’s floor (OpenSSL’s @SECLEVEL=0) is for a lab, not for production traffic. The same alert also appears in reverse: we forced a client to TLS 1.2 against a TLS 1.3-only server and got the identical tlsv1 alert protocol version.
No cipher suite in common
This is the case at the top of the page. With TLS 1.3 it is rare: RFC 8446 section 9.1 says a compliant application “MUST implement the TLS_AES_128_GCM_SHA256” suite, so two compliant stacks share at least one unless someone has configured it away. With a TLS 1.2 server trimmed to one or two suites, clients disagree, and they disagree differently. On our CCM-only server Node connected and everyone else failed. On a server limited to ECDHE-ECDSA-AES256-GCM-SHA384, both curl builds, both Pythons, Node and Chrome connected with default settings; the alert came back only when we forced the client to offer ChaCha20 alone.
Offer one suite at a time to map what a server accepts:
$ openssl s_client -connect localhost:18443 -servername localhost -CAfile root.pem -tls1_2 -cipher ECDHE-ECDSA-AES256-GCM-SHA384 -brief </dev/null
Connecting to 127.0.0.1
CONNECTION ESTABLISHED
Protocol version: TLSv1.2
Ciphersuite: ECDHE-ECDSA-AES256-GCM-SHA384
$ openssl s_client -connect localhost:18443 -servername localhost -CAfile root.pem -tls1_2 -cipher ECDHE-ECDSA-CHACHA20-POLY1305 -brief </dev/null
Connecting to 127.0.0.1
80A1C5FB01000000:error:0A000410:SSL routines:ssl3_read_bytes:tls alert handshake failure:ssl/record/rec_layer_s3.c:923:SSL alert number 40
The server-side fix is to offer ECDHE key exchange with AES-GCM or ChaCha20-Poly1305 alongside whatever legacy suite it was restricted to.
Expired certificate or a wrong clock
curl: (60) SSL certificate OpenSSL verify result: certificate has expired (10)
[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: certificate has expired (_ssl.c:1010)
CERT_HAS_EXPIRED: certificate has expired
Our test certificate ran from 1 January to 1 April 2025. Pull the dates from what the server actually presents, then check your own clock with date -u:
$ openssl s_client -connect localhost:18447 -servername localhost </dev/null 2>/dev/null | openssl x509 -noout -dates
notBefore=Jan 1 00:00:00 2025 GMT
notAfter=Apr 1 00:00:00 2025 GMT
A machine whose clock is far enough off sees valid certificates as not yet valid or expired. Chromium’s error list names “our clock is wrong” as one cause of ERR_CERT_DATE_INVALID.
The server wants a client certificate
Mutual TLS servers ask the client for a certificate. Without one, TLS 1.3 behaves in a way that confuses scripts: the client finishes its side of the handshake before the server checks, so the failure arrives on the first read, not during connect.
curl: (56) OpenSSL SSL_read: OpenSSL/4.0.3: error:0A00045C:SSL routines::tlsv13 alert certificate required, errno 0
curl: (56) LibreSSL SSL_read: LibreSSL/3.3.6: error:1404C45C:SSL routines:ST_OK:reason(1116), errno 0
curl exits 56, a receive error, not 35. httpx raised ReadError instead of ConnectError. LibreSSL prints only reason(1116). Node and requests named the alert, and Chrome showed net::ERR_BAD_SSL_CLIENT_AUTH_CERT. Supplying --cert client.pem --key client.key returned 200, and so did requests with cert=("client.pem", "client.key").
The proxy refused the CONNECT
For an HTTPS target, the client first asks the proxy to open a tunnel with CONNECT, defined in RFC 9110 section 9.3.6. Only after a 200 does any TLS begin. When the proxy says no, the client reports a tunnel failure, often in the same log line format as TLS errors.
$ curl -sS -v --cacert root.pem -x http://127.0.0.1:18461 https://localhost:18441/ -o /dev/null # trimmed
* Establishing HTTP proxy tunnel to localhost:18441
> CONNECT localhost:18441 HTTP/1.1
> Host: localhost:18441
> User-Agent: curl/8.23.0
> Proxy-Connection: Keep-Alive
>
< HTTP/1.1 407 Proxy Authentication Required
< Proxy-Authenticate: Basic realm="pw-test"
<
* CONNECT tunnel failed, response 407
curl: (7) CONNECT tunnel failed, response 407
The exit code is version-dependent. curl 8.7.1 exited 56 for the same 407. In the curl source, lib/cf-h1-proxy.c returns CURLE_RECV_ERROR after that message in the 8.19.0 tag and CURLE_COULDNT_CONNECT in 8.20.0. A script that treats exit 7 as “proxy unreachable” will misfile a wrong password on current curl.
| Proxy said | Meaning | Python requests 2.34.2 | Chrome 155 |
|---|---|---|---|
| 407 | Credentials missing or wrong | Tunnel connection failed: 407 Proxy Authentication Required |
ERR_INVALID_AUTH_CREDENTIALS |
| 403 | Proxy policy forbids that host or port | Tunnel connection failed: 403 Forbidden |
ERR_TUNNEL_CONNECTION_FAILED |
| 503 | Proxy could not reach the target | Tunnel connection failed: 503 Service Unavailable |
ERR_TUNNEL_CONNECTION_FAILED |
| No answer, port closed | Proxy itself unreachable | [Errno 61] Connection refused |
ERR_PROXY_CONNECTION_FAILED |
Chrome ran headless with no credentials to offer and reported the 407 as ERR_INVALID_AUTH_CREDENTIALS. Node’s built-in fetch hides the status two levels deep. With NODE_USE_ENV_PROXY=1 on Node 24.2.0, the 407 came back as TypeError: fetch failed. Its cause said Request was cancelled. and only the cause of that cause said Proxy response (407) !== 200 when HTTP Tunneling. Log err.cause.cause or you will never see it.
For the meaning of each status and what to change, the 403 vs 407 vs 429 guide and the proxy authentication entry go further. Two traps specific to TLS: --cacert covers the target, not the proxy, so a proxy listening on TLS needs --proxy-cacert (without it we got unable to get local issuer certificate (20) for the proxy’s own certificate); and in curl the 407 sits in %{http_connect}, while %{http_code} stays at 000.
The tunnel opened, then the far end hung up
This is the hardest one to read. The proxy returned 200, the client sent its ClientHello down the tunnel, and the connection closed with no alert. We reproduced it with a listener that reads the ClientHello and closes:
curl: (35) TLS connect error: error:0A000126:SSL routines::unexpected eof while reading
curl: (35) LibreSSL SSL_connect: SSL_ERROR_SYSCALL in connection to localhost:18450
[SSL: UNEXPECTED_EOF_WHILE_READING] EOF occurred in violation of protocol (_ssl.c:1010)
ECONNRESET: Client network socket disconnected before secure TLS connection was established
net::ERR_CONNECTION_CLOSED
Squid’s access log for the same request read TCP_TUNNEL/200 39 CONNECT localhost:18450. The proxy did its job and moved 39 bytes; the close came from beyond it. That log line, or %{http_connect} printing 200, is what separates this case from a proxy failure.
Who closes a connection after reading a ClientHello? A firewall or filter in front of the target. A target that refuses certain clients before the handshake completes; an anti-bot system can decide on the ClientHello alone, and our ClientHello study shows how differently libraries and browsers present themselves. Or a middlebox that mishandles a ClientHello too large for one packet.
That last cause is newer. Post-quantum key shares made ClientHellos bigger, and tldr.fail documents servers and middleboxes that fail when the message arrives in more than one TCP segment. We measured the first TLS record each client sent:
| Client | ClientHello (bytes) | Note |
|---|---|---|
| Chrome 155.0.8059.85, headless | 1,949 | Smallest of 6 attempts; range 1,949 to 2,013 |
| Node 24.2.0, OpenSSL 3.6.5 | 1,584 | Default settings |
| curl 8.23.0, OpenSSL 4.0.3 | 1,566 | Default settings |
| Python 3.12.13, requests 2.34.2, OpenSSL 3.6.5 | 1,529 | Default settings |
curl 8.23.0, --curves X25519 |
517 | Classical key share only |
| curl 8.7.1, LibreSSL 3.3.6 (macOS) | 319 | Default settings |
| Python 3.9.6, requests 2.32.3, LibreSSL 2.8.3 (macOS) | 209 | Default settings |
Every client built on OpenSSL 3.6.5 or 4.0.3 sent more than the 1,500-octet IP datagram an Ethernet link carries (RFC 894), and Chrome sent more still, so on a real network these ClientHellos span two TCP segments. OpenSSL 4.0.3 negotiated X25519MLKEM768 by default against our own server. If a target fails with a bare EOF from current clients but works from the old macOS curl, rerun with --curves X25519. If the 517-byte handshake succeeds where the 1,566-byte one fails, that points at a device in the path mishandling large ClientHellos, and the fix belongs to whoever runs it. tldr.fail spells out the server-side bug: the server must keep reading until it holds the whole record.
If the smaller handshake fails too, repeat the request without the proxy, or through another exit. The same failure from every path puts the cause at the target. A failure through one exit only puts it on that exit: its network, or the way the target treats its address.
Cloudflare 525, 526 and 1013
On a site behind Cloudflare, “SSL handshake failed” can appear as an error page with code 525, and it means something different from everything above. There are two TLS connections: visitor to Cloudflare, and Cloudflare to the site’s own server, the origin. Error 525, in Cloudflare’s words, “indicates that the SSL handshake between Cloudflare and the origin web server failed.” It occurs when the zone uses the Full or Full (strict) SSL mode.
If you are the visitor, your own handshake succeeded; Cloudflare served you the error page. Nothing on your device, browser or proxy will change it. Retry later or tell the site.
If you own the site, Cloudflare’s 525 page lists four causes to rule out at the origin: no valid SSL certificate installed, port 443 (or another custom secure port) not open, no SNI support, and cipher suites that do not match the ones Cloudflare uses. Three of the four map to sections above, and you can run the same openssl s_client checks against the origin’s address with -servername set to your hostname.
Error 526 is the verification variant. Cloudflare’s 526 page says it means Cloudflare “is unable to verify the SSL certificate on your origin server” while the zone is in Full (strict) mode. Again the visitor can do nothing. The owner checks that the origin certificate is unexpired, unrevoked, issued for the domain and served with its full chain, or installs a Cloudflare Origin CA certificate. Cloudflare also lists switching to the non-strict Full mode as a quick fix. Its Full mode page says that in this mode the origin certificate “will not be validated in any way”, so treat the switch as temporary.
Cloudflare’s 1xxx codes are a different family. Its 1xxx index notes that these “appear in the HTML body of the response”, which means the visitor’s TLS handshake with Cloudflare had already succeeded. A 1020 or 1015 page is an access or rate decision, not a handshake failure. The one 1xxx code that concerns TLS is 1013, “HTTP hostname and TLS SNI hostname mismatch”: the name in the ClientHello differs from the Host header. Cloudflare names two common causes, a browser setting the wrong SNI host and “a network proxying SSL traffic”. As a visitor, try once without the VPN, proxy or inspection software. As a developer, stop overriding Host by hand and use --resolve or --connect-to, as in the SNI section. A site owner cannot fix a mismatch the client creates, but can ask the affected user for the HAR file Cloudflare support requests.
The edge has its own handshake failure too. Cloudflare’s page on ERR_SSL_VERSION_OR_CIPHER_MISMATCH traces it to edge certificate problems the owner controls: a Universal certificate not yet active (Cloudflare says it should arrive “within 15 minutes to 24 hours of domain activation”), a DNS record set to DNS-only, an expired custom certificate, or a hostname two subdomain levels deep, which a Universal certificate does not cover.
A triage script that names the broken layer
When the message is ambiguous, walk the layers in order. This script uses only the standard library and stops at the first layer that fails: TCP, the proxy’s CONNECT, the TLS handshake, the certificate, then a first read to catch the TLS 1.3 client-certificate case.
#!/usr/bin/env python3
"""Say which layer broke: TCP, the proxy's CONNECT, the TLS handshake, or certificate checks.
Usage: python3 tls_triage.py HOST PORT [--proxy HOST:PORT [--proxy-auth USER:PASS]] [--cafile FILE]
Standard library only. Tested with Python 3.12.13 / OpenSSL 3.6.5."""
import argparse, base64, socket, ssl
ap = argparse.ArgumentParser()
ap.add_argument("host"); ap.add_argument("port", type=int)
ap.add_argument("--proxy"); ap.add_argument("--proxy-auth"); ap.add_argument("--cafile")
a = ap.parse_args()
def stage(name, ok, detail):
print(f"{name:<8} {'ok ' if ok else 'FAIL'} {detail}")
if not ok: raise SystemExit(1)
target = (a.proxy.rsplit(":", 1)[0], int(a.proxy.rsplit(":", 1)[1])) if a.proxy else (a.host, a.port)
try:
sock = socket.create_connection(target, timeout=10)
stage("tcp", True, f"connected to {target[0]}:{target[1]}")
except OSError as e:
stage("tcp", False, f"{target[0]}:{target[1]} {e}")
if a.proxy:
auth = ""
if a.proxy_auth:
auth = "Proxy-Authorization: Basic " + base64.b64encode(a.proxy_auth.encode()).decode() + "\r\n"
sock.sendall(f"CONNECT {a.host}:{a.port} HTTP/1.1\r\nHost: {a.host}:{a.port}\r\n{auth}\r\n".encode())
head = b""
while b"\r\n\r\n" not in head:
chunk = sock.recv(4096)
if not chunk: break
head += chunk
status = head.split(b"\r\n", 1)[0].decode(errors="replace")
stage("connect", status.split(" ")[1:2] == ["200"], status or "proxy closed the connection")
ctx = ssl.create_default_context(cafile=a.cafile)
try:
tls = ctx.wrap_socket(sock, server_hostname=a.host)
except ssl.SSLCertVerificationError as e:
stage("cert", False, e.verify_message)
except ssl.SSLError as e:
stage("tls", False, f"{e.reason} ({e.library})")
except OSError as e:
stage("tls", False, f"{type(e).__name__}: {e}")
issuer = dict(x[0] for x in tls.getpeercert()["issuer"]).get("commonName")
stage("tls", True, f"{tls.version()} {tls.cipher()[0]}, issuer CN={issuer}")
# TLS 1.3 servers can reject a client certificate after the handshake "succeeds",
# so read once to surface a late alert.
try:
tls.sendall(f"GET / HTTP/1.1\r\nHost: {a.host}\r\nConnection: close\r\n\r\n".encode())
first = tls.recv(64).split(b"\r\n", 1)[0].decode(errors="replace")
stage("read", bool(first), first or "closed without a response")
except ssl.SSLError as e:
stage("read", False, f"{e.reason} ({e.library})")
except OSError as e:
stage("read", False, f"{type(e).__name__}: {e}")
Output from four of the cases on this page:
$ python3 tls_triage.py localhost 18441 --proxy 127.0.0.1:18461 --cafile root.pem
tcp ok connected to 127.0.0.1:18461
connect FAIL HTTP/1.1 407 Proxy Authentication Required
$ python3 tls_triage.py localhost 18441 --proxy 127.0.0.1:18462 --cafile root.pem
tcp ok connected to 127.0.0.1:18462
connect ok HTTP/1.1 200 Connection established
cert FAIL self-signed certificate in certificate chain
$ python3 tls_triage.py localhost 18450 --proxy 127.0.0.1:18460 --cafile root.pem
tcp ok connected to 127.0.0.1:18460
connect ok HTTP/1.1 200 Connection established
tls FAIL UNEXPECTED_EOF_WHILE_READING (SSL)
$ python3 tls_triage.py localhost 18444 --cafile root.pem
tcp ok connected to localhost:18444
tls ok TLSv1.3 TLS_AES_256_GCM_SHA384, issuer CN=PW Test Intermediate CA
read FAIL TLSV13_ALERT_CERTIFICATE_REQUIRED (SSL)
For a real provider, pass the gateway as --proxy gw.example.net:8080 --proxy-auth user:pass. The per-library proxy settings are in the Python proxy guide and the Node.js proxy guide.
How these errors were produced
All output on this page was captured on 21 October 2026 on one Mac (Apple silicon, macOS 26.6.2), against servers bound to 127.0.0.1 that we started for the test. Every test request went to 127.0.0.1. Each client ran each case once; these errors are deterministic, and where a second run was made the text did not change. Certificates came from a throwaway test CA with one intermediate.
| Port | Server | What it simulates |
|---|---|---|
| 18441 | openssl s_server 4.0.3, full chain |
Healthy control |
| 18442 | Same, -tls1_3 |
TLS 1.3 only |
| 18443 | Same, -tls1_2 -cipher ECDHE-ECDSA-AES256-GCM-SHA384 |
One TLS 1.2 suite |
| 18444 | Same, -Verify 1 |
Client certificate required |
| 18445 to 18448 | Same, with bad certificates | Self-signed, wrong name, expired, leaf without intermediate |
| 18449 | Python http.server |
Plain HTTP on a port used as TLS |
| 18450 | Python socket | Reads the ClientHello, then closes |
| 18451 | Python ssl with an SNI callback |
Refuses a ClientHello without SNI |
| 18452 | openssl s_server -tls1 |
Legacy TLS 1.0 server |
| 18453 | openssl s_server -tls1_2 -cipher ECDHE-ECDSA-AES256-CCM |
Unusual single suite |
| 18460 to 18463 | Squid 6.13 | Open proxy, Basic auth proxy, ssl_bump interception, TLS listener |
Clients: curl 8.23.0 on OpenSSL 4.0.3 (Homebrew), curl 8.7.1 on LibreSSL 3.3.6 (macOS), Python 3.12.13 on OpenSSL 3.6.5 with requests 2.34.2, urllib3 2.8.0 and httpx 0.28.1, Python 3.9.6 on LibreSSL 2.8.3 with requests 2.32.3, Node 24.2.0 on OpenSSL 3.6.5, and Chrome 155.0.8059.85 driven headless over the DevTools protocol, reading the errorText that Page.navigate returns. Because Chrome does not trust a private test root, the protocol cases ran with --ignore-certificate-errors-spki-list set to the test leaf key only, and proxy runs used --proxy-bypass-list=<-loopback> so localhost traffic went through the proxy. Squid’s ACLs refused every destination except localhost, which also blocked Chrome’s own background requests. ClientHello sizes came from a socket listener that read the 5-byte TLS record header, then the full record, and logged the length; one connection per client, except Chrome, which made six attempts, reconnecting after each close.
Frequently asked questions
What does "SSL handshake failed" mean?
How do I fix SSL handshake failed in curl?
Why does the request work in my browser but fail in Python or curl?
Can a proxy cause SSL handshake failed?
Is it safe to disable certificate verification to get past the error?
What is Cloudflare error 525 SSL handshake failed?
Sources
- RFC 8446 section 6: TLS 1.3 alert protocol and alert codes
- RFC 8446 section 9.1: mandatory-to-implement cipher suites
- RFC 6066 section 3: Server Name Indication
- RFC 8996: Deprecating TLS 1.0 and TLS 1.1
- RFC 9110 section 9.3.6: CONNECT
- RFC 894: Transmission of IP datagrams over Ethernet
- libcurl error codes
- curl 8.20.0 source: lib/cf-h1-proxy.c
- Chromium net_error_list.h
- Cloudflare docs: Error 525
- Cloudflare docs: Error 526
- Cloudflare docs: Full SSL mode
- Cloudflare docs: 1xxx errors
- Cloudflare docs: Error 1013
- Cloudflare docs: ERR_SSL_VERSION_OR_CIPHER_MISMATCH
- tldr.fail: servers that mishandle large ClientHellos
- CPython issue 62817: AIA chasing for missing intermediate certificates
- Node.js CLI: NODE_EXTRA_CA_CERTS
- Node.js CLI: NODE_USE_ENV_PROXY
- Requests: CA certificates
- HTTPX: SSL
- urllib3: HTTPS proxy error with an HTTP proxy
- Squid configuration: ssl_bump