---
title: "cURL Timeout Explained: Settings, Fixes & Examples"
description: "Learn how cURL timeouts work, how to set them, and how to fix common timeout errors. Improve reliability of your cURL requests with simple examples."
url: "https://marsproxies.com/blog/curl-timeout/"
---

- [EN ](https://marsproxies.com/blog/curl-timeout/?locale-change "English")
  [CN](https://marsproxies.cn/blog/curl-timeout/?locale-change "Chinese")

[Contact sales](https://marsproxies.com/contact-sales/) [Register](https://dashboard.marsproxies.com/register/) [Log in](https://dashboard.marsproxies.com/login/)

[Contact sales](https://marsproxies.com/contact-sales/) [Register](https://dashboard.marsproxies.com/register/) [Log in](https://dashboard.marsproxies.com/login/)

[Contact sales](https://marsproxies.com/contact-sales/)

[Log in](https://dashboard.marsproxies.com/login/) [Register](https://dashboard.marsproxies.com/register/)

- [EN ](https://marsproxies.com/blog/curl-timeout/?locale-change "English")
  [CN](https://marsproxies.cn/blog/curl-timeout/?locale-change "Chinese")

[Back to blog](https://marsproxies.com/blog/) April 24, 2026

# cURL Timeout Explained: Settings, Fixes & Examples

[How to](https://marsproxies.com/blog/category/how-to/)

\-

Table of contents

1. [What is a cURL timeout?](https://marsproxies.com/blog/curl-timeout/#b-what-is-a-curl-timeout)
2. [Types of cURL timeouts](https://marsproxies.com/blog/curl-timeout/#b-types-of-curl-timeouts)
3. [Default cURL timeout behavior](https://marsproxies.com/blog/curl-timeout/#b-default-curl-timeout-behavior)
4. [How to set timeouts in cURL](https://marsproxies.com/blog/curl-timeout/#b-how-to-set-timeouts-in-curl)
5. [Total operation timeout: --max-time](https://marsproxies.com/blog/curl-timeout/#b-total-operation-timeout---max-time)
6. [Connect timeout: --connect-timeout](https://marsproxies.com/blog/curl-timeout/#b-connect-timeout---connect-timeout)
7. [Slow transfer timeout: --speed-limit & --speed-time](https://marsproxies.com/blog/curl-timeout/#b-slow-transfer-timeout---speed-limit----speed-time)
8. [libcurl timeout options](https://marsproxies.com/blog/curl-timeout/#b-libcurl-timeout-options)
9. [Common cURL timeout errors & how to fix them](https://marsproxies.com/blog/curl-timeout/#b-common-curl-timeout-errors--how-to-fix-them)
10. [Error 28: operation timed out](https://marsproxies.com/blog/curl-timeout/#b-error-28-operation-timed-out)
11. [“Operation timed out after X ms with 0 bytes received”](https://marsproxies.com/blog/curl-timeout/#b-operation-timed-out-after-x-ms-with-0-bytes-received)
12. [Debugging timeouts with -v and --trace-time](https://marsproxies.com/blog/curl-timeout/#b-debugging-timeouts-with--v-and---trace-time)
13. [How to choose the right timeout values](https://marsproxies.com/blog/curl-timeout/#b-how-to-choose-the-right-timeout-values)

\-

By default, the cURL command can hang indefinitely if a server doesn’t respond. This is because there’s no timeout for the entire operation unless you set one. In practice, cURL requests can stall your whole script if they hang.

For reliability, always set appropriate timeout parameters so cURL won’t wait forever: if an operation exceeds your limit, it stops and returns an error instead of freezing.

## What is a cURL timeout?

A [cURL](https://marsproxies.com/blog/curl-command/) timeout is a limit on how long a request is allowed to run when using cURL. Without timeouts, cURL might wait forever for a response that isn’t coming. This can lead to hanging scripts, wasted resources, and frustrating delays.

Timeouts matter because they protect your applications from unreliable servers, poor internet connections, and unexpected delays. If a request takes too long, cURL will stop and report an error, thus allowing your script or program to handle the issue cleanly, such as by retrying or logging the failure.

There are several kinds of timeouts you can set: a connect timeout for the time it takes to connect to the server, a maximum time for the entire operation, and a low-speed timeout if the transfer becomes too slow. Each plays a role in ensuring your cURL requests don’t hang or fail silently.

## Types of cURL timeouts

cURL provides a few options to control how long it waits:

- **Total timeout (--max-time):** The maximum time in seconds for the entire request. If this time is exceeded, cURL aborts with a timeout error.
- **Connect timeout (--connect-timeout):** The maximum time to establish the connection (DNS lookup + handshake). If the server isn’t connected within that limit, cURL stops the attempt (timeout error 28).
- **Slow transfer timeout:** Aborts the transfer if data speed stays below a specified rate for too long.
- **Millisecond precision options (libcurl):** If you're using libcurl (cURL’s underlying library in code), you can set timeouts with millisecond accuracy using options like *CURLOPT\_TIMEOUT\_MS* and *CURLOPT\_CONNECTTIMEOUT\_MS*. These are useful for applications needing precise control over timeout values.

## Default cURL timeout behavior

If you don’t set any timeouts, here’s what happens:

- **No overall limit**

By default, there is no max time set, and cURL could wait indefinitely for the operation to complete. No cURL max time limit is enforced unless you specify one.

- **Default cURL connect timeout**

cURL has a built-in timeout for the connection phase of about 300 seconds (5 minutes). This default is quite high, so it’s often lowered with a custom *--connect-timeout*.

- **No slow-transfer cutoff**

The low-speed abort is off by default, so even a very slow or stalled transfer will keep going.

- **Bottom line**

Relying on defaults is risky since cURL requests could hang forever and block your program. It’s better to explicitly set a cURL connect timeout and a total timeout so you control how long cURL will wait.

## How to set timeouts in cURL

You can configure timeouts when running the cURL command using these options:

### Total operation timeout: --max-time

Sets an upper limit (maximum time in seconds) for the total request duration. If the transfer exceeds this time, cURL will terminate it. The following example caps the request at 30 seconds.

```javascript
curl --max-time 30 https : / /example.com
```

### Connect timeout: --connect-timeout

Limits how long cURL waits to connect to the host (including DNS resolution). The following example makes cURL give up if it cannot connect within 5 seconds.

```javascript
curl --connect-timeout 5 https : / /example.com 
```

### Slow transfer timeout: --speed-limit & --speed-time

Tells cURL to abort a transfer that’s too slow. The following example will stop the download if the speed drops below 1,000 bytes per second for 15 seconds.

```javascript
curl --speed-limit 1000 --speed-time 15 https : / /example.com/file.zip
```

### libcurl timeout options

In libcurl, corresponding options match the above. For example:

- *CURLOPT\_TIMEOUT* sets the total timeout (default 0, meaning no limit)
- *CURLOPT\_CONNECTTIMEOUT* sets the connection timeout (default 300 seconds)

There are also millisecond-resolution versions (*CURLOPT\_TIMEOUT\_MS*, etc.), and low-speed threshold options (*CURLOPT\_LOW\_SPEED\_LIMIT* and *CURLOPT\_LOW\_SPEED\_TIME*) to abort slow transfers.

## Common cURL timeout errors & how to fix them

### Error 28: operation timed out

Error 28 is cURL’s code for a timeout. It indicates the transfer did not finish within the specified timeout. You might see “...0 bytes received” in the error message. This means no data at all was received from the server before the timeout. To fix it, increase your timeout-related values if they were too low, or check for network/server slowness.

### “Operation timed out after X ms with 0 bytes received”

This is a common message that means cURL hit its maximum time limit (like *--max-time*), or the connection timeout expired before receiving any data. If this happens frequently, it might indicate DNS resolution issues, an unresponsive server, or network connectivity problems.

### Debugging timeouts with -v and --trace-time

To investigate where your cURL request is hanging, use the *-v* flag for verbose output. This shows each stage of the connection, including DNS resolution and SSL handshakes. Add *--trace-time* to timestamp every line of the log. Together, these options help you see if the delay is during the cURL connect timeout, data transfer, or somewhere else in the whole operation.

## How to choose the right timeout values

Choosing the right values depends on the type of request you're making and the conditions of your network. There's no one-size-fits-all, but here are some general guidelines to help you set timeouts more effectively.

- **APIs:** Use a short timeout (2–5 seconds) and a max time of 10–30 seconds. APIs (especially paired with [proxies](https://marsproxies.com/blog/using-proxy-with-curl-guide/)) are typically fast, and long delays usually mean something’s wrong.
- **Browser-like web requests:** Use a timeout of 5–10 seconds and a maximum time of 30–60 seconds to allow for larger HTML responses or redirects.
- **Large downloads:** You can set a higher maximum time allowed, such as 300–900 seconds, but still keep the timeout short (5–10 seconds). Also consider enabling low-speed aborts with *--speed-limit* and *--speed-time* to stop stalled transfers.
- **CLI tools & scripts:** Always set a timeout explicitly to prevent scripts from hanging. A good default: *--connect-timeout 5* and *--max-time 30*.

When picking values, balance these three factors:

- **Timeout length:** Too short may cause premature failures; too long may block your app.
- **Retry logic:** If you’re retrying failed requests, shorter timeouts work better.
- **Network conditions:** For unstable networks, increase timeouts slightly to reduce false timeouts.

Working with authenticated APIs? Our guide on [cURL bearer tokens](https://marsproxies.com/blog/curl-bearer-token/) covers how to handle token-based auth alongside your timeout settings.

What is the default curl timeout?

By default, cURL has no set timeout for the full operation. It will wait indefinitely unless you set a timeout. The only built-in limit is a 300-second cURL connect timeout for the connection phase (around 5 minutes).

What is the difference between --max-time and --connect-timeout?

*--connect-timeout* only limits the time spent establishing the connection (DNS lookup and handshake). *--max-time* (the cURL max time) caps the duration of the whole operation from start to finish. Connect-timeout is just for the initial connection, whereas *--max-time* limits the entire request.

How do I set a curl timeout under 1 second?

Use fractional seconds. For example, *--connect-timeout 0.5* sets a 0.5s timeout, and *--max-time 0.5* sets a 0.5s total timeout. (If you’re using libcurl in code, you can use the millisecond options like *CURLOPT\_TIMEOUT\_MS* for the same effect.)

Why does curl timeout even when the server is online?

“Online” doesn’t guarantee the server will respond quickly. cURL will timeout if the server or network is too slow to deliver data within your set time limit. In other words, the server may be up, but if it doesn’t send a response before your timeout (due to slowness or network lag), cURL treats it as a timeout.

How do I debug curl timeout errors?

Run the cURL command with *-v* to see which step is stalling (DNS, connect, etc.), and add *--trace-time* to a trace log to timestamp each operation. This helps pinpoint where the delay is so you can set a timeout or fix the network issue.

[Learn more](https://dashboard.marsproxies.com/register/)

\-

Author

[Lukas Tilkevicius Growth & Partnerships Manager](https://marsproxies.com/blog/authors/lukas-tilkevicius/)

Table of contents

1. [What is a cURL timeout?](https://marsproxies.com/blog/curl-timeout/#b-what-is-a-curl-timeout)
2. [Types of cURL timeouts](https://marsproxies.com/blog/curl-timeout/#b-types-of-curl-timeouts)
3. [Default cURL timeout behavior](https://marsproxies.com/blog/curl-timeout/#b-default-curl-timeout-behavior)
4. [How to set timeouts in cURL](https://marsproxies.com/blog/curl-timeout/#b-how-to-set-timeouts-in-curl)
5. [Total operation timeout: --max-time](https://marsproxies.com/blog/curl-timeout/#b-total-operation-timeout---max-time)
6. [Connect timeout: --connect-timeout](https://marsproxies.com/blog/curl-timeout/#b-connect-timeout---connect-timeout)
7. [Slow transfer timeout: --speed-limit & --speed-time](https://marsproxies.com/blog/curl-timeout/#b-slow-transfer-timeout---speed-limit----speed-time)
8. [libcurl timeout options](https://marsproxies.com/blog/curl-timeout/#b-libcurl-timeout-options)
9. [Common cURL timeout errors & how to fix them](https://marsproxies.com/blog/curl-timeout/#b-common-curl-timeout-errors--how-to-fix-them)
10. [Error 28: operation timed out](https://marsproxies.com/blog/curl-timeout/#b-error-28-operation-timed-out)
11. [“Operation timed out after X ms with 0 bytes received”](https://marsproxies.com/blog/curl-timeout/#b-operation-timed-out-after-x-ms-with-0-bytes-received)
12. [Debugging timeouts with -v and --trace-time](https://marsproxies.com/blog/curl-timeout/#b-debugging-timeouts-with--v-and---trace-time)
13. [How to choose the right timeout values](https://marsproxies.com/blog/curl-timeout/#b-how-to-choose-the-right-timeout-values)

Categories

- [Antidetect solutions](https://marsproxies.com/blog/category/antidetect-solution/)

  [3](https://marsproxies.com/blog/category/antidetect-solution/)
- [Comparisons](https://marsproxies.com/blog/category/comparisons/)

  [3](https://marsproxies.com/blog/category/comparisons/)
- [How to](https://marsproxies.com/blog/category/how-to/)

  [121](https://marsproxies.com/blog/category/how-to/)
- [Insights](https://marsproxies.com/blog/category/insights/)

  [86](https://marsproxies.com/blog/category/insights/)
- [Product news](https://marsproxies.com/blog/category/product-news/)

  [5](https://marsproxies.com/blog/category/product-news/)
- [Sneaker Bots](https://marsproxies.com/blog/category/sneaker-bots/)

  [2](https://marsproxies.com/blog/category/sneaker-bots/)

## Related articles

[How to](https://marsproxies.com/blog/category/how-to/)

### [How to Bypass Pornhub Ban Using Proxies (2026 Guide)](https://marsproxies.com/blog/how-to-bypass-pornhub-ban/)

Bypass Pornhub age verification block safely with our 2026 proxy guide. Learn which countries and states block Pornhub and how to access it.

[Lukas Tilkevicius Growth & Partnerships Manager](https://marsproxies.com/blog/authors/lukas-tilkevicius/)

October 12, 2026

[How to](https://marsproxies.com/blog/category/how-to/)

### [How to Set Up a Proxy Server on PS5 (Step-by-Step Guide)](https://marsproxies.com/blog/proxy-server-on-ps5/)

Learn how to set up a proxy server on your PS5. Follow our easy guide to configure proxy settings, speed up downloads, and bypass blocks.

[Lukas Tilkevicius Growth & Partnerships Manager](https://marsproxies.com/blog/authors/lukas-tilkevicius/)

October 7, 2026

[How to](https://marsproxies.com/blog/category/how-to/)

### [How to Use Node Unblocker for Web Scraping & Privacy](https://marsproxies.com/blog/node-unblocker/)

Learn how to use Node Unblocker for web scraping, privacy, and bypassing restrictions. Follow setup steps, use cases, benefits, and key limitations.

[Dalius Pamedytis Software Engineer](https://marsproxies.com/blog/authors/dalius-pamedytis/)

October 6, 2026