cURL Timeout Explained: Settings, Errors, and Fixes

The cURL command-line tool is incredibly useful when working with APIs, servers, or automated scripts. But if you want to ensure your data retrieval process is reliable and efficient, you need to set a timeout in cURL requests and manage them properly.

In this article, we’ll help you understand the importance of timeouts in cURL, the common errors you might see, and how to set and debug timeouts effectively.

What Is a cURL Timeout?

The timeout happens when your request to a server takes too long and cURL stops waiting for a response. Instead of hanging indefinitely when a connection or operation takes too long, it simply terminates it and reports an error.

By setting a timeout, you determine how long cURL should wait for a response. This way, you make sure the connection stays reliable and your application responsive, even when the external resource is unresponsive or slow.

Here are a few real-world use cases that show why timeouts with cURL are important:

• Slow APIs

If the API you’re calling isn’t responsive, whether because the server is overloaded or it’s processing a heavy request, your script could get stuck. Without a timeout, it can wait indefinitely for a response that may never arrive.

By setting a timeout, you give the cURL request a clear limit: If the API doesn’t respond within this specific time, stop and move on. This prevents your script and even your whole workflow from freezing because of one slow API call.

• Network delays

Packet loss, loss of internet connection, or poor routing can cause your cURL request to take much longer than expected, resulting in slow or failed connections.

Setting a timeout ensures you don’t end up waiting for a response that’s stuck in transit. Your script will have a clear time limit, allowing it to retry, log the issue, or move on instead of stalling.

• DNS resolution delays

If the DNS server is slow or the domain doesn’t exist, resolving the domain name can take a long time or fail completely. A timeout ensures your cURL request won’t hang indefinitely during DNS lookup, allowing your script to fail fast and try again with another DNS server or fallback option.

Common cURL Timeout Errors and What They Mean

Seeing a timeout error means that cURL has encountered a problem. Let’s break down the most common ones.

• cURL: (28) Connection timed out

This error indicates the cURL request waited longer than the specified timeout and was canceled. It usually points to client-side issues when the timeout value you set, or the default, was too short for the server. When the server is overloaded, unresponsive, or too slow, it’s a server-side timeout.

• cURL: (7) Failed to connect to host

The most common reason you’re seeing this timeout error is that you have an incorrect URL, a DNS issue, or a firewall blocking the connection. While it’s usually client-side, it can also be caused by server-side issues, or the server or host you’re trying to reach is unavailable.

• cURL: (52) Empty reply from server

Seeing this timeout error means the connection was established, but the server didn’t send back a valid response. It’s usually a server-side error when the server crashes, resets, or closes the connection before sending data. Although rarely, it can sometimes be a client-side timeout, caused by a misconfigured SSL /TLS or proxy.

How to Set a Timeout in cURL

The cURL command-line tool gives you several options to control how long it should wait before giving up. Here are the most common timeout options, which are especially useful in scripts, web scraping, and other automated processes.

• –connect-timeout

This option allows you to set the connection timeout, or the number of seconds cURL should wait to establish a connection. It’s useful when you know the server is usually fast but sometimes unavailable.

Here’s an example:

curl --connect-timeout 5 https://iproyal.com

This means the IPRoyal server has five seconds to accept the connection. If it doesn’t, cURL will exit with an error.

• --max-time

This option lets you set the maximum time for the entire operation. That means the total time, including DNS resolution, connection, and response. You can use it when calling APIs, running automated scripts, or anywhere else where strict limits can help prevent slow responses from blocking your workflow.

For example:

curl --max-time 10 https://iproyal.com/slow-api

The maximum time in this command is 10 seconds, so cURL will stop waiting after that, even if the IPRoyal server is connected successfully but is taking too long to reply.

Common Scenarios

You can combine both timeouts for complete control over both the connection phase and the total operation.

Here’s how to set a timeout in cURL in different scenarios.

Basic API Request

To fetch data from a server using a GET request , you can use cURL with a connection timeout and a maximum time:

curl --connect-timeout 5 --max-time 15 https://iproyal.com/slow-api

This command instructs cURL to wait up to 5 seconds to establish a connection with the server, and a total of 15 seconds for the entire operation - the connection, sending the request, and receiving the response.

You can also use a POST request with -X POST and -d to send data while respecting timeouts.

Downloading Large Files

Using timeouts when downloading files with cURL will help you manage long downloads more efficiently.

curl --connect-timeout 10 --max-time 3000 -O https://www.iproyal.com/large-file.zip

This means cURL gives the IPRoyal server up to 10 seconds to establish a connection and limits the total download time to 3,000 seconds.

Proxy Integration

Using a proxy with cURL for reasons such as efficient web scraping and unrestricted data access can be more reliable when combined with timeouts.

curl --connect-timeout 5 --max-time 30 --proxy geo.iproyal.com:12321 --proxy-connect-timeout 3 https://iproyal.com/api/proxy-list

This means the cURL request will wait up to 5 seconds to connect to the target server through the proxy, allow a total of 30 seconds for the entire request, and wait up to 3 seconds to connect to the proxy server itself.

You can add a custom user agent (-A ('MyAgent/1.0 ‘) or include basic authentication (-u username:password) with cURL to identify or authenticate your requests when using proxies.

Overall, you can use this timeout combination for web scraping, automated monitoring, or CI/CD pipelines to avoid delays at any stage of the cURL request.

Debugging cURL Timeout Issues

To understand what’s going on behind your timeout issue, you need to see the full communication, not just the response body.

Here are a few standard cURL command line arguments to help you troubleshoot and resolve the issue more effectively, rather than guessing.

-v (Verbose Mode)

Verbose mode prints out the entire connection process in real-time.

curl -v https://iproyal.com

It displays detailed information about the DNS resolution, the SSL/TLS handshake, request headers, protocol details, and response codes. Use it when you just need a quick look at what’s happening.

--trace and --trace-time

These arguments provide a complete log of the request lifecycle. The --trace option prints all incoming and outgoing data, while --trace-time adds precise timestamps:

curl --trace-time --trace debug.log https://iproyal.com

The output is saved into the debug log and includes DNS lookups, SSL/TLS handshake details, timing for each phase of the connection, redirect chains, and headers.

As a result, you can easily see exactly where a stall occurs - DNS, SSL, or server response.

--stderr

If you don’t want error messages mixed into the standard output, you can use the --stderr argument to redirect them into a separate file.

curl https://iproyal.com --stderr errors.txt

This saves all error messages to errors.txt, making it easier to analyze or share logs without clutter.

In short, here’s how these debugging options help you spot timeout issues:

• If DNS resolution is slow, the issue is probably your local resolver or network.
• If the SSL handshake fails, you may have a certificate or TLS version mismatch.
• If the response stalls after headers, the target server may be overloaded or throttling.

These arguments provide a clear picture of the entire cURL request flow, helping you identify the exact reason why the timeout occurred and fix the root cause rather than guessing.

Using cURL Timeout in Scripts and Automation

If you’re using cURL in automation such as bash scripts, cron jobs, or CI/CD pipelines, timeouts help keep things efficient and prevent delays. That way, one bad cURL request won’t block the entire process.

Here’s an example bash script:

#!/bin/bash

URL="https://iproyal.com/api"
MAX_RETRIES=3
TIMEOUT=10

for i in $(seq 1 $MAX_RETRIES); do
    echo "Attempt $i..."
    if curl --max-time $TIMEOUT --silent --fail $URL; then
        echo "Success!"
        exit 0
    else
        echo "Request failed, retrying in 5s..."
        sleep 5
    fi
done

echo "All attempts failed."
exit 1

This script limits each request to 10 seconds, retries up to three times, and waits five seconds between retries. As a result, it won’t wait forever if the server doesn’t respond, but it will give the server a chance to recover if it was busy.

If all retries fail, the script exits with an error code, notifying other processes that the job has failed.

Here are a few best practices when using cURL in:

• Bash scripts: always use --max-time and optionally --connect-timeout to prevent requests from hanging indefinitely
• Cron jobs: combine timeouts with retries and minor delays between attempts to avoid piling up failed jobs when a server is slow or temporarily unavailable
• CI/CD pipelines: use --fail to ensure failed requests trigger clear error codes, allowing the pipeline to fail fast and prevent stuck deployments

Logging errors separately with --stderr or into a debug file can also help monitor and troubleshoot issues efficiently.

Conclusion

cURL is an excellent tool for working with APIs, web services, or automated scripts. However, without correctly set timeouts, requests can hang forever, slowing down your workflows.

By understanding and using timeout and debugging options, you can effectively control the connection and total operation time, pinpoint the exact cause of timeout issues, and respond efficiently. As a result, your scripts and automation will run seamlessly and reliably, saving time and avoiding unnecessary delays.