Error: socket hang up in Node.js (tested)

Error: socket hang up with code: 'ECONNRESET' means the connection closed before a response arrived. The cause can be the server, the client, or a stale keep-alive socket. We reproduced each cause in Node 24 and recorded what http.request, fetch and axios report.

1. What "socket hang up" means

Node's http client throws Error: socket hang up when the socket closes after the request was sent but before any response headers came back. The error code is always ECONNRESET, even when the close was a clean FIN and not a TCP reset.

If the headers already arrived and the body is cut off, you get a different error: Error: aborted on the response object. Built-in fetch (undici) never says "socket hang up". It throws TypeError: fetch failed and puts the real reason in err.cause.

2. Our test setup

We ran a Node 24.21.0 HTTP server and an HTTPS server on localhost, plus a raw TCP server that speaks minimal HTTP/1.1. Each scenario was hit with three clients: http.request, built-in fetch, and axios 1.20.0. We logged err.name, err.message, err.code and err.cause.

3. Results: the exact error per cause and client

curl against the "destroy without responding" server prints curl: (52) Empty reply from server. That is the same event seen from curl.

4. When the client hangs up itself

A "socket hang up" can be your own code. Calling req.destroy() before the response arrives gives exactly the same message as a server-side close. This is the most confusing case.

Two lessons. The timeout option of http.request only emits an event; it does not cancel anything. And if you destroy on timeout, you get "socket hang up", which looks like a server fault. Pass an error to make it clear: req.destroy(new Error('client timeout')). The server sees this as a client abort, which nginx logs as 499 Client Closed Request.

5. The stale keep-alive race

In Node 24 http.globalAgent has keepAlive: true (we printed its options). Idle sockets are reused. If the server closes an idle socket at the same moment the client sends a new request on it, the request fails.

We built a raw TCP server that closes idle connections after 1000 ms and does not send a Keep-Alive: timeout header (like many proxies and non-Node servers). We sent a request, waited 970 to 1030 ms, then sent another.

The window is a few milliseconds wide. In production, with thousands of requests, it turns into a steady trickle of random errors.

Against a Node 24 server with keepAliveTimeout = 1000 we saw 0 failures with all three clients, even with keepAliveTimeoutBuffer = 0. The Node server sends Keep-Alive: timeout=1, and the clients dropped the socket before reusing it (reusedSocket was false every time). Also, Node 24 servers have keepAliveTimeoutBuffer = 1000 by default: with keepAliveTimeout = 1000 the server really closed the idle socket after 2002 ms. More on the header in Keep-Alive and Connection headers.

6. How to fix it

• Find out who closed. Check server logs for a crash or a timeout at the same time. A ECONNREFUSED right after a hang up means the server process died.
• Client idle timeout below the server's. Set the agent's idle timeout lower than the server's (or proxy's, or load balancer's) keep-alive timeout. In our test, timeout: 900 against a 1000 ms server removed every failure.
• Retry idempotent requests once on a reused socket. The failures all had req.reusedSocket === true. Retry GET, HEAD, PUT and DELETE in that case. Do not blindly retry POST.
• Check the scheme and port. http:// to an HTTPS port is a hang up; https:// to an HTTP port is EPROTO "wrong version number".
• Handle client timeouts on purpose. Use AbortSignal.timeout() with fetch, or req.destroy(new Error('timeout')) with http, so your logs say "timeout" instead of "socket hang up".
• Raise server timeouts for slow handlers (server.setTimeout, proxy read timeouts), or make the endpoint asynchronous.

const agent = new http.Agent({ keepAlive: true, timeout: 50_000 }); // server/LB idle is 60 s

function get(url, retried = false) {
  return new Promise((resolve, reject) => {
    const req = http.get(url, { agent }, resolve);
    req.on('error', err => {
      if (!retried && req.reusedSocket && err.code === 'ECONNRESET') {
        return resolve(get(url, true));   // stale socket: retry once
      }
      reject(err);
    });
  });
}

For fetch, undici's Agent has its own keepAliveTimeout option (per the undici docs, not measured here). For the server-side view of resets, read ERR_CONNECTION_RESET / ECONNRESET. Behind a proxy, the same race shows up as 502 Bad Gateway.

Written with AI assistance. Measured on 2026-10-02 with Node.js 24.21.0 (http.request, built-in fetch/undici), axios 1.20.0 and curl 8.14.1 against local Node and raw TCP test servers. Lines marked as from the docs were not measured. PlainHeaders is our extension; Node.js, axios and curl are free.