A PHP cURL request hangs, times out, or fails with no message
cURL error 28: Operation timed outShort answer
PHP's cURL has no timeout of its own: CURLOPT_TIMEOUT defaults to 0 (never) and the connect phase waits up to 300 seconds. Set both options, then check curl_exec() with === false and read curl_errno() and curl_error() before you close the handle. Error 28 means a timeout fired.
Fix it fast
1Find out which cause you have
Run the request once with a short limit and print the error number and message. Error 28 is a timeout; 6 and 7 are DNS and connect failures.
<?php $ch = curl_init('https://example.com/api'); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_TIMEOUT, 10); $body = curl_exec($ch); if ($body === false) { echo curl_errno($ch) . ': ' . curl_error($ch); }2Match what you see, then jump to its fix
- 1
The request hangs for minutes, or the script dies at max_execution_time instead of failing cleanlyNo timeout is set, so the call waits as long as the server lets itFix - 2
Error 28 straight away when CURLOPT_TIMEOUT_MS is under 1000The timeout is in milliseconds but resolves to an instant failureFix - 3
curl_exec() returns false, the page is blank, no messageThe failure is swallowed because the return value is never checkedFix - 4
The code receives an error page as if it were dataYou want HTTP 4xx and 5xx answers to count as errorsFix
- 1
What does the error look like?
cURL error 28: Operation timed outcurl_exec() returns false and nothing is shownthe page waits a long time before the request fails
Cause 1 of 4
No timeout is set, so the call waits as long as the server lets it
1Check
CURLOPT_TIMEOUT is the limit for the whole transfer, in seconds, and its default is 0, which means no limit. CURLOPT_CONNECTTIMEOUT covers only the connect phase (DNS and handshakes) and defaults to 300 seconds. Search your code for both options.
grep -rn "CURLOPT_TIMEOUT\|CURLOPT_CONNECTTIMEOUT" src/ app/2Fix
Set a short connect timeout and a total timeout. The total limit includes the connect time and always wins, so keep the connect value lower.
curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 5);
curl_setopt($ch, CURLOPT_TIMEOUT, 15);3Verify
Point the request at an address that does not answer and confirm it fails after about the limit, with error 28 or 7.
$start = microtime(true);
curl_exec($ch);
echo round(microtime(true) - $start, 1) . 's ' . curl_errno($ch);Confirmed by curl.se
Cause 2 of 4
The timeout is in milliseconds but resolves to an instant failure
1Check
The millisecond options are CURLOPT_TIMEOUT_MS and CURLOPT_CONNECTTIMEOUT_MS. With the standard system name resolver, the DNS part still uses full seconds, with a minimum of one second, so a very small value can expire immediately.
grep -rn "_MS" src/ app/2Fix
Use the millisecond options with values of 1000 or more, or use the plain seconds options.
curl_setopt($ch, CURLOPT_CONNECTTIMEOUT_MS, 3000);
curl_setopt($ch, CURLOPT_TIMEOUT_MS, 10000);3Verify
Run the request against a healthy URL and confirm it now succeeds.
echo curl_getinfo($ch, CURLINFO_HTTP_CODE);Confirmed by php.net
Cause 3 of 4
The failure is swallowed because the return value is never checked
1Check
curl_exec() returns false on a transport failure such as DNS, connect, SSL or timeout. Compare with === false, because a plain falsy check is not reliable. A 404 or 500 answer is not a failure for cURL, so read the status code separately.
grep -rn "curl_exec" src/ app/2Fix
Test for false, read curl_errno() and curl_error() before curl_close() (closing clears the message), and check the HTTP status for the success path.
$body = curl_exec($ch);
if ($body === false) {
$code = curl_errno($ch);
$msg = curl_error($ch);
curl_close($ch);
throw new RuntimeException("cURL $code: $msg");
}
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);3Verify
Request a host that does not exist and confirm your exception carries a code and a message.
$ch = curl_init('http://nonexistent.invalid/');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
var_dump(curl_exec($ch), curl_errno($ch), curl_error($ch));Confirmed by php.net
Cause 4 of 4
You want HTTP 4xx and 5xx answers to count as errors
1Check
By default cURL returns the body of a 400 or higher answer and reports no error.
echo curl_getinfo($ch, CURLINFO_HTTP_CODE);2Fix
Set CURLOPT_FAILONERROR so cURL fails for status 400 and above, or test the status code yourself after the call.
curl_setopt($ch, CURLOPT_FAILONERROR, true);3Verify
Request a URL that returns 404 and confirm curl_exec() now returns false.
var_dump(curl_exec($ch), curl_error($ch));Confirmed by php.net
How do I stop it coming back?
- Wrap every cURL call in one helper that always sets both timeouts and checks the result.
- Keep the total timeout below your PHP max_execution_time and below any proxy timeout in front of the app.
- Log curl_errno() and the URL on every failure so slow third parties show up in logs.
- Retry only calls that are safe to repeat, and use a small, fixed number of tries.
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
Back 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 fixBack end
AWS SDK for PHP cannot get credentials from the instance profile metadata server
Error retrieving credentials from the instance profile metadata server.
The SDK tries the EC2 instance metadata service when it has no valid credentials from anywhere earlier in its chain.
4 causes, each with a fixBack end
AWS SDK for PHP rejects requests: the signature is from the future
Signature not yet current: {date} is still later than {date}
AWS compares the timestamp in your signed request with its own clock.
2 causes, each with a fix