TypeError: fetch failed (ECONNREFUSED)

What it means

Node.js’s built-in fetch throws TypeError: fetch failed when it cannot connect, and puts the reason in cause. We pointed clients at a port where nothing listened:

Client	Message
TypeScript v1, TypeScript v2 (default)	TypeError: fetch failed, cause ECONNREFUSED
TypeScript v2 with versionNegotiation: 'auto'	Version negotiation probe failed: fetch failed (code ERA_NEGOTIATION_FAILED)

The second message mentions version negotiation only because the probe is the first request. Nothing about versions went wrong.

The server is not running on that port

Start the server and look at the port it prints. Then:

curl -i -X POST http://127.0.0.1:8000/mcp

Any HTTP answer, even an error, means the connection works and the problem is elsewhere. Connection refused from curl confirms nothing listens there. If the server exits right after starting, read its output: it may be EADDRINUSE.

The server listens on a different interface

A server bound to 127.0.0.1 accepts connections only from the same machine. This matters when:

• the client runs in Docker or WSL and the server on the host, or the other way round;
• you use localhost and it resolves to IPv6 ::1 while the server listens on IPv4 only. Try 127.0.0.1 explicitly.

For containers, publish the port and bind the server to 0.0.0.0 inside the container, then add the Host check allowance and authentication.

Related

• Error POSTing to endpoint: the server answered, but at the wrong path.
• Run a server behind Docker and a reverse proxy