fetch failed 🟩 Node.js

TypeError: fetch failed (cause: ConnectTimeoutError / ECONNREFUSED / UND_ERR)

Node’s built-in fetch (undici) couldn’t complete the request; the real reason is in error.cause.

Seen on: Node.js

Meaning

Node 18+ fetch wraps network errors as "fetch failed". Log err.cause: UND_ERR_CONNECT_TIMEOUT (unreachable/IPv6 issues), ECONNREFUSED, ENOTFOUND, or certificate errors.

Common causes

  • Server unreachable / connect timeout
  • localhost resolving to IPv6 ::1 while the server listens on IPv4
  • DNS failure
  • TLS certificate issues
  • Proxy required but not configured (fetch ignores HTTP_PROXY)

⚡ Quick fix

  1. console.error(err.cause) to see the real error
  2. Use 127.0.0.1 instead of localhost
  3. Configure an undici ProxyAgent for corporate proxies

Detailed fix by platform

Node.js

  1. try { await fetch(url); } catch (e) { console.error(e.cause); }

How to diagnose

  1. Cause — What is err.cause?
  2. Address — IPv4 vs IPv6?

🧠 Still stuck? Analyze your error

Paste the full message, response headers or stack trace — we'll detect the platform and point to the most likely cause.