PHP cURL cannot connect to a server that requires TLS 1.2
TLS 1.2 not working in cURLShort answer
A server that requires TLS 1.2 rejects a client that offers an older version. In PHP the version is controlled by CURLOPT_SSLVERSION. Set it to CURL_SSLVERSION_TLSv1_2, which means TLS 1.2 or later, and remove any option that forces SSLv3 or TLS 1.0. Check curl_version() to see which library and cURL version PHP uses.
Fix it fast
1Find out which cause you have
Print the cURL version and the TLS library PHP's curl extension uses.
php -r 'print_r(curl_version());' | grep -E "version|ssl_version"2Match what you see, then jump to its fix
What does the error look like?
TLS 1.2 not working in cURLThe handshake fails only against servers that require TLS 1.2 or newer
Cause 1 of 2
Your code forces an old protocol version
1Check
SSLv2 is disabled by default since libcurl 7.18.1 and SSLv3 since 7.39.0, and both are refused entirely since 7.77.0. Search your code for a forced version.
grep -rn "CURLOPT_SSLVERSION" src vendor/ 2>/dev/null | head2Fix
Remove the forced value, or set TLS 1.2 as the minimum. CURL_SSLVERSION_TLSv1_2 means TLS 1.2 or later, so newer versions still work.
curl_setopt($ch, CURLOPT_SSLVERSION, CURL_SSLVERSION_TLSv1_2);3Verify
Run the request again and confirm it returns a body.
php request.phpConfirmed by curl.se
Cause 2 of 2
A maximum version below what the server needs
1Check
CURL_SSLVERSION_MAX_* caps the highest version libcurl will negotiate. Before libcurl 7.61.0 the default maximum was TLS 1.2, and from 7.61.0 it is TLS 1.3 if the TLS library supports it.
grep -rn "CURL_SSLVERSION_MAX" src | head2Fix
Drop the maximum, or use MAX_DEFAULT. If you need to pin both ends, combine a minimum and a maximum with a bitwise OR.
// allow TLS 1.2 and newer, no cap
curl_setopt($ch, CURLOPT_SSLVERSION, CURL_SSLVERSION_TLSv1_2);
// pin exactly TLS 1.2 only if the server requires it
curl_setopt($ch, CURLOPT_SSLVERSION, CURL_SSLVERSION_TLSv1_2 | CURL_SSLVERSION_MAX_TLSv1_2);3Verify
Repeat the request. The connection completes.
php request.phpConfirmed by curl.se
How do I stop it coming back?
- Do not hard-code SSL versions; set a minimum of TLS 1.2 and leave the maximum open.
- Keep PHP and its cURL library updated through your operating system's updates.
- Log curl_error() for every failed request.
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?
Projects of mine built on the same technologies:
Related fixes
Servers
curl stops with 'sslv3 alert handshake failure' on an HTTPS request
error:14094410:SSL routines:ssl3_read_bytes:sslv3 alert handshake failure
The server answered curl's TLS hello with a handshake_failure alert, so it refused to agree on something.
3 causes, each with a fixBack end
Composer or PHP stream fails with certificate verify failed
SSL certificate problem: unable to get local issuer certificate
PHP could not check the server's TLS certificate against a trusted CA file.
3 causes, each with a fixBack end
Android gets HTML instead of JSON from a PHP API
org.json.JSONException: Value <br of type java.lang.String cannot be converted to JSONObject
The response body is not JSON.
2 causes, each with a fixBack end
Apache returns 403 when a URL contains %3F
a request like /page%3Fname=test is refused while /page?name=test works
Recent Apache httpd blocks a rewrite when the request contains an encoded question mark (%3F) and the rewritten target has a literal ?.
2 causes, each with a fixBack end
Apache returns 500 with Premature end of script headers
500 Internal Server Error
Apache ran your script, but the script printed no valid HTTP header before its output.
3 causes, each with a fixBack end
Apache returns 503 or 504 because PHP-FPM did not answer in time
Error dispatching request
Apache sent the request to PHP-FPM and gave up waiting.
3 causes, each with a fix