Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

Node.js request fails with 'socket hang up' and code ECONNRESET

ErrorError: socket hang up

Short answer

The other side closed the connection before a full response arrived. Node.js reports it as ECONNRESET. It happens when a keep-alive socket is reused just as the server closes it, when the server drops the connection after a timeout or crash, or when your own server timeouts fire.

  • Applies to Node.js 22, Node.js 24
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Check whether the failing request used a reused keep-alive socket, and read the server's own log for the same moment.

    // in the client, on the failing request
    req.on('error', (err) => console.log(err.code, req.reusedSocket));
  2. 2Match what you see, then jump to its fix

    1. 1err.code is ECONNRESET, req.reusedSocket is true, and it happens now and then rather than on every callA reused keep-alive socket was closed by the server at the same momentFix
    2. 2err.code is ECONNRESET and req.reusedSocket is false, or the server log shows a restart or an uncaught exception at that timeThe server or the peer dropped the connection (crash, restart, timeout)Fix
    3. 3Large uploads or slow clients fail, and the server answers 408 or closes the socketThe Node.js server closes slow requests with its own timeoutsFix

What does the error look like?

  • Error: socket hang up
  • code: 'ECONNRESET'

Cause 1 of 3

A reused keep-alive socket was closed by the server at the same moment

1Check

The Node.js docs say that with a keep-alive agent, if the server closes the connection just as the agent reuses it, the request can fail with ECONNRESET. The server default keepAliveTimeout is 5000 ms.

grep -rn -E "keepAlive|keepAliveTimeout" src

2Fix

Retry idempotent requests when reusedSocket is true. The docs also describe agentKeepAliveTimeoutBuffer (default 1000 ms), which makes the agent close sockets slightly before the server does.

const http = require('node:http');
const agent = new http.Agent({ keepAlive: true });

function retriableRequest() {
  const req = http
    .get('http://localhost:3000', { agent }, (res) => {
      // ...
    })
    .on('error', (err) => {
      if (req.reusedSocket && err.code === 'ECONNRESET') {
        retriableRequest();
      }
    });
}

retriableRequest();

3Verify

Run a loop of requests; the reused-socket failures should be retried and no error should reach your code.

node client.js

Confirmed by nodejs.org

Did this fix it?

Cause 2 of 3

The server or the peer dropped the connection (crash, restart, timeout)

1Check

Node.js describes ECONNRESET as a connection forcibly closed by a peer, normally from a loss of the connection on the remote socket due to a timeout or reboot.

curl -v http://localhost:3000/health

2Fix

Find why the peer closed the socket: read its log at that second, fix a crash or restart, and handle the 'error' event on the request so the process does not exit.

req.on('error', (err) => {
  console.error('request failed', err.code);
});

3Verify

Repeat the request after the server is stable; it should return a status code.

curl -i http://localhost:3000/health

Confirmed by nodejs.org

Did this fix it?

Cause 3 of 3

The Node.js server closes slow requests with its own timeouts

1Check

The server docs say that when headersTimeout or requestTimeout expires, the server responds with 408 and closes the connection. headersTimeout defaults to the lower of requestTimeout and 60000 ms; requestTimeout defaults to 300000 ms.

grep -rn -E "headersTimeout|requestTimeout" src

2Fix

Raise requestTimeout for the server that takes large uploads, or make the client send the data faster. Keep both non-zero.

const server = http.createServer({
  headersTimeout: 60000,
  requestTimeout: 600000,
}, handler);

3Verify

Upload the same large file again.

curl -i -T big-file.bin http://localhost:3000/upload

Confirmed by nodejs.org

Did this fix it?

How do I stop it coming back?

  • Always attach an 'error' listener to outgoing requests.
  • Retry only idempotent requests, and only when reusedSocket is true.
  • Keep keep-alive settings of client and server written down together.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Back end

ng serve says it cannot determine the project or target

Cannot determine project for command.

The Angular CLI looked through angular.json for a project that defines the target you asked for (serve, build, test) and found none, or found several and could not pick one.

3 causes, each with a fix

Back end

ng serve cannot find the dev-server builder package

Could not find the implementation for builder @angular/build:dev-server

The builder named in angular.json (for example @angular-devkit/build-angular:dev-server) is looked up as an npm package starting from the workspace root.

3 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.