TypeError: fetch failed — cause: ECONNRESET (Node.js built-in fetch/undici)

What causes this error

Node's global fetch is implemented on top of undici. When the underlying TCP/TLS connection fails, undici wraps the specific error inside a generic TypeError: fetch failed, so the useful detail — a reset connection, a timeout, a bad certificate — is one level deeper than most people think to look.

The Fix

try {
  const res = await fetch('https://api.example.com/data');
} catch (err) {
  console.error('fetch failed:', err.message);
  console.error('root cause:', err.cause); // the actual network error is here
}

Common underlying causes surfaced via error.cause: ECONNRESET (server closed the connection mid-request — often an overloaded upstream or a proxy timeout), ETIMEDOUT, or `UND_ERR_CONNECT_TIMEOUT` for slow DNS/connect phases.

Common causes / variations

• An upstream server closing keep-alive connections more aggressively than your client's connection pool expects
• No request timeout set, so a hung connection eventually gets reset by an intermediary (load balancer, proxy)
• Self-signed or expired TLS certificates on internal services

Related errors

See also: AbortSignal.timeout TimeoutError, CORS error.