Timeouts: ETIMEDOUT, deadlines, and hung requests
"Timed out" never says what timed out. Every request crosses several separately timed stages — DNS, TCP connect, TLS, sending, waiting for first byte, reading the body — and the fix depends entirely on which timer fired.
Which timer fired?
Connect timeout (ETIMEDOUT during dial) | SYN packets went unanswered. Unlike ECONNREFUSED (fast, active rejection), this is silence — usually a firewall dropping packets, a wrong IP, or an unreachable network. More time will not help. |
| Read / response timeout | Connected fine, then the server took too long to answer: slow query, cold start, overload, or a genuinely long operation with too small a budget. |
| Idle/socket timeout | Data stopped flowing mid-body. Long streams and large downloads through proxies hit this — every hop (client, proxy, load balancer, server) has its own idle limit and the smallest one wins. |
| Deadline exceeded (gRPC, context) | A whole-operation budget expired, possibly propagated from a caller. The timeout you see may have been set several services upstream. |
Diagnose with stage timings
curl -w 'dns %{time_namelookup} connect %{time_connect} tls %{time_appconnect} ttfb %{time_starttransfer} total %{time_total}\n' \
-o /dev/null -s https://api.example.com/slow
One line tells you where the time went. High connect: network/firewall. High
ttfb: the server is slow — profile it, don't tune the client. Total fine but
your app times out anyway: your client's budget is smaller than reality, or an intermediate
proxy (common default: 30–60s) is cutting in before your own timer.
Choosing budgets
No timeout is a defect — a hung dependency then hangs you, and thread or connection pools drain until everything is "down" from one slow backend. Set explicit budgets on every external call: tight for connect (1–3s — dialing is fast when it works), generous only for the specific slow operations that earn it. Retry only on failures that happened before the server could act (connect timeouts), or on idempotent requests — a response timeout does not mean the work didn't happen, and blind retries double-charge and pile load onto an already-slow server. Under sustained latency, prefer failing fast (circuit breaking) over queueing more waiting requests.
Documented occurrences
3,154 analyzed errors across 613 libraries match this failure class. Each links to the thrown message, its source line, and documented fixes.
can1357/oh-my-pi
- 124: git timed out after {timeout:.0f}s
- AnthropicConnectionTimeoutError
- ${argv[0]} did not report a tunnel URL within ${READY_TIMEOUT_MS / 1000}s
- Browser open timed out after ${timeoutMs}ms
- Command timed out
- +50 more in oh-my-pi
hashicorp/nomad
- Consul Gateway Proxy connection_timeout must be set
- error parsing GCSTimeout: %w
- error parsing GitTimeout: %w
- error parsing HgTimeout: %w
- error parsing HTTPReadTimeout: %w
- +44 more in nomad
karatelabs/karate
- async drain timed out
- CDP timeout for: {method}
- chrome failed to start or no page targets available within timeout (${timeout}ms)
- listen timed out after <timeoutMs>ms
- page load timeout after %dms - url: %s, strategy: %s, domContentEventFired: %s, framesStillLoading: %s, mainFrameId: %s, expectedLoaderId: %s, supersededLoaderId: %s, committedLoaderId: %s, domContentLoaderId: %s, readyState: %s, jsExec: %s, cdpOpen: %s
- +37 more in karate
BerriAI/litellm
- AnthropicException Timeout - {error_str}
- APITimeoutError - Request timed out. Error_str: {error_str}
- Azure Document Intelligence operation polling timed out after {timeout_secs} seconds
- AzureException Timeout - {message}
- BedrockException: Timeout Error - {error_str}
- +34 more in litellm
nautechsystems/nautilus_trader
- Blockchain execution transaction limits are required: allowed_token_pairs, slippage_bps, max_slippage_bps, max_order_amount, deadline_seconds, max_quote_age_blocks, receipt_timeout_secs
- connection timed out after {}s
- data-connect timeout
- disconnect readiness timeout while waiting for engine disconnections
- disconnect timeout while disconnecting clients
- +34 more in nautilus_trader
jackwener/OpenCLI
- App launched but CDP not available on port ${port} after ${POLL_TIMEOUT_MS / 1000}s
- Douyin search did not render result cards within the timeout. Open the same search in Chrome and verify login/security state before retrying.
- 'gemini image', timeoutSeconds, 'Gemini was still generating at the deadline. Re-run with a higher --timeout.'
- Image upload did not complete before timeout
- Instagram private publish configure_sidecar timed out waiting for video transcode
- +32 more in OpenCLI
openai/codex
- command timed out
- current-time request timed out after {}s
- features.multi_agent_v2.default_wait_timeout_ms must be at least features.multi_agent_v2.min_wait_timeout_ms
- features.multi_agent_v2.default_wait_timeout_ms must be at most features.multi_agent_v2.max_wait_timeout_ms
- features.multi_agent_v2.min_wait_timeout_ms must be at most features.multi_agent_v2.max_wait_timeout_ms
- +32 more in codex
cilium/cilium
- Cilium API client timeout exceeded
- connectivity test suite timeout (%s) reached
- etcd client timeout exceeded
- exec timeout
- failed to create cilium agent client after %f seconds timeout: %w
- +30 more in cilium
Hmbown/CodeWhale
- API timeout should publish an Interrupted mailbox lifecycle event
- Codewhale account login timed out; run `codewhale account login` to try again
- Command timed out after {}ms
- {COORDINATION_LOCK_TIMEOUT_MARKER} for {}: {error}
- DS4 /v1/models timed out after 15 seconds at {}
- +29 more in CodeWhale
paperclipai/paperclip
- ${action} timed out: ${result.stderr.trim()}
- Cloud artifacts timed out for ${sha}; missing: ${missing.join(", ")}.
- Cloud readiness requires positive finite timeout and poll interval.
- Cloud source verification timed out for ${sha}. Rerun Cloud readiness before retrying the release.
- Cloudflare sandbox bridge request timed out after ${requestTimeoutMs}ms.
- +27 more in paperclip
…and 603 more libraries — search for your exact message.