What Is ETIMEDOUT? – Definition and How to Fix It

Learn what the ETIMEDOUT error means, how connect and read timeouts differ, and how to diagnose and fix each cause.

ETIMEDOUT is an operating-system socket error meaning an operation did not complete within its time limit. It is a transport failure, not an HTTP response — no status code, no body.

1. Two Different Timeouts

The distinction determines the diagnosis, and most confusion comes from conflating them.

A connect timeout means you never reached the server. A read timeout means you did, and it did not answer in time. They are fixed differently.

2. Why Connect Timeouts Look Different From Refusals

A refused connection returns ECONNREFUSED immediately — something answered and said no. A connect timeout means nothing answered at all, which is what a firewall dropping packets silently looks like.

That difference is the fastest diagnostic available: instant failure points at a closed port or a dead service, while a slow failure points at packets being discarded on the way.

3. Set Both Timeouts Separately

import requests

r = requests.get(url, timeout=(10, 60))   # 10s connect, 60s read

const controller = new AbortController();
const t = setTimeout(() => controller.abort(), 30_000);
try {
  const res = await fetch(url, { signal: controller.signal });
} finally {
  clearTimeout(t);
}

A short connect timeout and a longer read timeout is the right shape: connections either establish quickly or not at all, whereas a legitimate response can be slow. A single combined value forces one of the two to be wrong.

Never omit a timeout. The default in several clients is unbounded, and one stalled request holds a worker forever.

4. Diagnosing by Layer

1. DNS — does the name resolve at all? A resolution failure is EAI_AGAIN or ENOTFOUND, not ETIMEDOUT.
2. TCP — does a plain connection to the port succeed?
3. TLS — does the handshake complete? A hang here is a connect-phase timeout.
4. HTTP — does a minimal request return anything?

Working up the layers separates a network problem from a server problem in a couple of minutes, rather than guessing at client settings.

5. Common Causes in Collection Work

• Proxy failure. A dead or overloaded proxy times out on connect. Test the same URL direct to isolate it.
• Rate limiting by silence. Some defences stop responding rather than returning 429, so throttling appears as timeouts.
• Concurrency too high, exhausting local sockets or the proxy pool.
• Server-side slowness on heavy queries — a search with many filters can genuinely exceed a short read timeout.
• IPv6 routes that resolve but do not work, where forcing IPv4 fixes it instantly.
• Connection-pool exhaustion, where the timeout is waiting for a pool slot rather than the network.

6. Retrying Correctly

Timeouts are usually transient, so retry — but with care about method and cause.

• Retry idempotent requests freely with exponential backoff and jitter.
• Do not blindly retry a non-idempotent request on a read timeout: the server may have processed it, and you cannot tell.
• Cap attempts. Retrying a systematically unreachable host is only a slower failure.
• Rotate the proxy between attempts, since the proxy is the most likely culprit.
• Treat a rising timeout rate as throttling and reduce concurrency rather than retrying harder.

That last point is the one that matters most in practice: retrying into a rate limit expressed as silence makes it worse.

7. Fix Checklist

1. Distinguish connect from read by where it failed.
2. Test direct, bypassing any proxy.
3. Verify DNS, TCP, and TLS separately.
4. Set explicit, separate timeouts on every request.
5. Lower concurrency and see whether the rate falls.
6. Retry idempotent requests with backoff and a different proxy.
7. Log the phase and the elapsed time, so patterns are visible later.

8. Summary

ETIMEDOUT is a socket-level timeout with no HTTP status: a connect timeout means the server was never reached, a read timeout means it did not answer in time.

Set both explicitly and separately, diagnose upward from DNS to HTTP, suspect the proxy first in collection work, and read a rising timeout rate as throttling to back off from rather than retry through.

Potential Related Glossary

• Residential Proxies
• IP Rotation
• Web Crawling
• Concurrency vs Parallelism