ETIMEDOUT
The connection attempt timed out before receiving a response.
Usually happens because:
- ☑ Server Overloaded
- ☑ Silent Firewall Drops
- ☑ Strict Client Timeout Limit
🔍 Quick Checklist:
What is ETIMEDOUT?
ETIMEDOUT stands for 'Connection Timed Out'. It is thrown when a network request, handshake, or TCP connection takes longer than the client's configured timeout limit. If the target server is unreachable, overloaded, or drops packets silently, the operating system or client library closes the socket after a period of inactivity, throwing ETIMEDOUT.
Common Causes
- Server Overloaded: The backend API is busy processing heavy operations and fails to reply within the timeout threshold.
- Silent Firewall Drops: Network firewalls drop packets instead of rejecting them, leaving the client waiting until the timeout limits expire.
- Strict Client Timeout Limit: The client-side application timeout is configured too aggressively (e.g. 50ms).
| Cause | Frequency |
|---|---|
| Server Overloaded | ⭐⭐⭐⭐⭐ |
| Silent Firewall Drops | ⭐⭐⭐⭐ |
| Strict Client Timeout Limit | ⭐⭐⭐ |
Common Mistakes
- Setting connection timeouts too short for heavy backend endpoints (like report generations or CSV exports).
- Failing to handle timeout errors, leading to hung script execution states.
How to Fix
Framework-Specific Examples
Applying timeouts inside Next.js API Routes using an AbortController.
export async function GET() {
const controller = new AbortController();
const id = setTimeout(() => controller.abort(), 5000);
try {
const res = await fetch('https://api.com/data', { signal: controller.signal });
clearTimeout(id);
return Response.json(await res.json());
} catch (err: any) {
if (err.name === 'AbortError') {
return new Response('Request Timed Out', { status: 504 });
}
return new Response('Error', { status: 500 });
}
}Server Configuration Examples
Increasing Nginx read and connection timeouts for slow backends.
server {
proxy_read_timeout 300s;
proxy_connect_timeout 60s;
}Best Practices
- Use pagination or asynchronous background tasks for heavy computations.
- Check server load metrics during peak times.
Frequently Asked Questions (FAQ)
Q: What is the difference between connect and read timeouts?
Connect timeout is the time spent establishing the TCP connection. Read timeout is the time spent waiting for data packets to arrive after the connection is established.
Q: Why does a firewall cause ETIMEDOUT instead of ECONNREFUSED?
Firewalls can be configured to drop packets silently. Since no reject packet is returned, the client keeps waiting until it hits connection timeout limits.
Q: How do I configure request timeouts in standard fetch?
Fetch does not have a timeout parameter. You must use an `AbortController` and call `controller.abort()` using a `setTimeout` timer.
Q: Can I automatically retry timed-out requests?
Yes. Axios-retry or similar libraries can catch ETIMEDOUT and automatically retry the request, but make sure the endpoint is idempotent (safe to run twice).