ETIMEDOUT / connect ETIMEDOUT (Node fetch, axios, database)
A client tried to open a TCP connection (or waited for a response) and gave up. ETIMEDOUT means silence — nothing accepted or answered in time — not a clean “connection refused” reset.
What ETIMEDOUT means
In Node (libuv) Error: connect ETIMEDOUT is errno ETIMEDOUT: SYN packets got no accepting handshake before the connect timeout. Libraries wrap it as axios ETIMEDOUT, undici/fetch failures, SequelizeConnectionError, MongoServerSelectionError: … timed out, Redis Connection timeout, etc. A request timeout (response headers never arrived) is related but configured separately from the TCP connect timeout.
Error: connect ETIMEDOUT 203.0.113.10:5432
at TCPConnectWrap.afterConnect [as oncomplete] (node:net:…)
# axios: error.code === 'ETIMEDOUT'
# fetch: TypeError: fetch failed → cause.code === 'ETIMEDOUT'ETIMEDOUT vs ECONNREFUSED vs others
| Code | What happened | Typical meaning |
|---|---|---|
ETIMEDOUT | No reply in time | Filtered port, wrong network path, host down blackhole, very slow route |
ECONNREFUSED | TCP RST / nothing listening | Wrong port or process not started — see ECONNREFUSED |
ENOTFOUND | DNS failed | Bad hostname — see ERR_NAME_NOT_RESOLVED |
ECONNRESET | Peer closed mid-stream | Proxy/LB idle timeout, server crash, TLS mismatch fallout |
ERR_SOCKET_TIMEOUT / undici | Headers/body wait exceeded | Raise timeout only after fixing the slow dependency |
Cause table
| Situation | Likely cause | Fix |
|---|---|---|
| DB/API from app server | Security group / firewall drops packets | Allow app → DB port; avoid 0.0.0.0 open; check NACLs |
| Works locally, fails in Docker | localhost is the container | Use service name / host.docker.internal / host gateway IP |
| HTTPS URL to HTTP port | TLS speaking to plain socket (often hangs then fails) | Match scheme and port; see SSL guides |
| Corporate laptop | HTTP_PROXY/HTTPS_PROXY required or broken | Set or unset proxy env; configure NO_PROXY for internal hosts |
| IPv6 AAAA first | Broken IPv6 path | Try IPv4 literal; fix dual-stack; compare with curl -4/-6 |
| Server under load | Accept queue / DB connections exhausted | Metrics, pool sizes, scale; don’t only raise client timeout |
Debug steps
- From the same machine/container as the app:
curl -v --connect-timeout 5 host:portornc -vz host port. - Confirm DNS:
getent hosts name/dig— wrong IP is a silent timeout later. - Compare connect vs whole-request timeouts in your client (
axios.timeout, undiciconnectTimeout, DB poolacquire). - Check firewalls both ways and whether the service listens on
127.0.0.1only vs0.0.0.0. - If it is intermittent, look at load balancers’ idle timeouts and connection pooling.
# Quick TCP check (Linux)
nc -vz db.internal 5432
curl -v --connect-timeout 5 https://api.example.com/health
# axios: surface the code
try {
await axios.get(url, { timeout: 10_000 });
} catch (err) {
console.error(err.code, err.cause?.code, err.message);
}Related networking pages: ECONNREFUSED, localhost refused to connect, TypeError: Failed to fetch, ERR_NAME_NOT_RESOLVED, too many redirects.
Related
TypeError: fetch failed (Node) · net::ERR_CONNECTION_TIMED_OUT · HTTP 504 Gateway Timeout · getaddrinfo ENOTFOUND · ECONNRESET · WebSocket connection failed · HTTP 206 Partial Content · download won't resume
Questions
What does connect ETIMEDOUT mean in Node?
The TCP handshake (or configured connect wait) expired without a successful connection — usually firewall, wrong network, or a host that never answers.
How is ETIMEDOUT different from ECONNREFUSED?
REFUSED means something answered with a reset (nothing listening). TIMED OUT means silence / filtered path.
Why does it work on my laptop but time out in production?
Different VPC/security groups, private DNS, or proxy requirements. Debug from the production network namespace.
Should I just increase the timeout?
Only after checking connectivity. A higher timeout on a blackholed port just makes failures slower.
Can DNS cause ETIMEDOUT?
Bad DNS usually shows ENOTFOUND first. A resolved-but-unreachable IP then times out on connect.
Do Docker and localhost interact badly here?
Yes — localhost inside a container is not the host. Use the compose service name or a host gateway.
Published .