TypeError: fetch failed (Node.js) — how to fix
TypeError: fetch failed
at node:internal/deps/undici/undici:13502:13
at async main (/app/index.js:3:15) {
[cause]: Error: connect ECONNREFUSED 127.0.0.1:3000
at TCPConnectWrap.afterConnect [as oncomplete] (node:net:1607:16) {
errno: -111,
code: 'ECONNREFUSED',
syscall: 'connect',
address: '127.0.0.1',
port: 3000
}
}
Quick fix: Log the cause: catch (e) { console.error(e.cause) }. ECONNREFUSED on localhost: use http://127.0.0.1:PORT instead of localhost (Node 17+ may resolve it to ::1). ENOTFOUND: fix the hostname/DNS. Certificate errors: set NODE_EXTRA_CA_CERTS=/path/ca.pem. Behind a proxy, use undici's ProxyAgent (setGlobalDispatcher(new ProxyAgent(url))).
What it means
Since Node 18, fetch() is built in (implemented by undici). When the request fails before any HTTP response arrives, it rejects with a generic TypeError: fetch failed. HTTP errors like 404 or 500 do not cause this; they resolve normally with res.ok === false.
The useful information is in error.cause, which many loggers and frameworks (Next.js, Remix, Nuxt) hide. Print it:
try {
const res = await fetch(url);
} catch (err) {
console.error(err.cause ?? err);
}
Then match the cause code below.
Cause 1: ECONNREFUSED — nothing listening, or localhost → IPv6
Node 17+ no longer reorders DNS results to prefer IPv4, so localhost can resolve to ::1. If your API only listens on 127.0.0.1, the connection is refused:
[cause]: Error: connect ECONNREFUSED ::1:3000
Fixes:
await fetch("http://127.0.0.1:3000/api"); // explicit IPv4
or make the server listen on all interfaces (app.listen(3000, "0.0.0.0") or "::"), or run Node with --dns-result-order=ipv4first.
If the address is IPv4 and still refused, the server isn't running on that port. Check with curl -v http://127.0.0.1:3000 or ss -ltnp | grep 3000.
In Docker, localhost is the container itself. Call the other service by its Compose service name (http://api:3000), or host.docker.internal to reach the host.
Cause 2: ENOTFOUND / EAI_AGAIN — DNS lookup failed
[cause]: Error: getaddrinfo ENOTFOUND api.exmaple.com
Check for typos and that the URL has a scheme (https://). Then test DNS from the same machine: nslookup api.example.com. EAI_AGAIN is a temporary DNS failure; see Temporary failure in name resolution.
Cause 3: UND_ERR_CONNECT_TIMEOUT / UND_ERR_HEADERS_TIMEOUT
undici's default connect timeout is 10 s and headers/body timeouts are 300 s. A firewall dropping packets, or an IPv6 route that doesn't work, produces a connect timeout. Node 20+ tries addresses in turn ("happy eyeballs", autoSelectFamily); on older versions try --dns-result-order=ipv4first.
Set your own timeout to fail fast:
await fetch(url, { signal: AbortSignal.timeout(5000) });
Cause 4: TLS certificate errors
[cause]: Error: unable to get local issuer certificate
code: 'UNABLE_TO_GET_ISSUER_CERT_LOCALLY'
Common behind corporate proxies that re-sign HTTPS. Give Node the company CA:
export NODE_EXTRA_CA_CERTS=/path/to/corp-ca.pem
node app.js
Other codes: SELF_SIGNED_CERT_IN_CHAIN, CERT_HAS_EXPIRED, ERR_TLS_CERT_ALTNAME_INVALID. See unable to get local issuer certificate. Avoid NODE_TLS_REJECT_UNAUTHORIZED=0 outside quick local tests.
Cause 5: an HTTP proxy is required
Built-in fetch ignores HTTP_PROXY/HTTPS_PROXY by default. Use undici's proxy agent:
import { setGlobalDispatcher, ProxyAgent } from "undici";
setGlobalDispatcher(new ProxyAgent(process.env.HTTPS_PROXY));
Newer Node versions (24+, and 22.21+) honour the variables when started with NODE_USE_ENV_PROXY=1.
Cause 6: other side closed / ECONNRESET
[cause]: SocketError: other side closed means the server or a load balancer closed the connection, often a keep-alive socket that timed out on the server side. Retry idempotent requests, or check the server's logs and keep-alive timeout.
Next.js and server components
During next build, server-side fetch to your own API route (http://localhost:3000/api/...) fails because no server is running at build time. Call the data function directly instead of fetching your own API, or make the page dynamic.
Last updated 2026-11-14.