Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

A PHP cURL request hangs, times out, or fails with no message

ErrorcURL error 28: Operation timed out

Short 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.

  • Applies to PHP 8.3, PHP 8.4, libcurl 8.x
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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);
    }
  2. 2Match what you see, then jump to its fix

    1. 1The 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. 2Error 28 straight away when CURLOPT_TIMEOUT_MS is under 1000The timeout is in milliseconds but resolves to an instant failureFix
    3. 3curl_exec() returns false, the page is blank, no messageThe failure is swallowed because the return value is never checkedFix
    4. 4The code receives an error page as if it were dataYou want HTTP 4xx and 5xx answers to count as errorsFix

What does the error look like?

  • cURL error 28: Operation timed out
  • curl_exec() returns false and nothing is shown
  • the 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

Did this fix it?

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

Did this fix it?

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

Did this fix it?

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

Did this fix it?

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

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 fix

Next step

Want this handled for good?

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