Node.js request fails with 'socket hang up' and code ECONNRESET
Error: socket hang upShort 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.
Fix it fast
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));2Match what you see, then jump to its fix
- 1
err.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
err.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
Large uploads or slow clients fail, and the server answers 408 or closes the socketThe Node.js server closes slow requests with its own timeoutsFix
- 1
What does the error look like?
Error: socket hang upcode: '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" src2Fix
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.jsConfirmed by nodejs.org
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/health2Fix
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/healthConfirmed by nodejs.org
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" src2Fix
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/uploadConfirmed by nodejs.org
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 fixBack end
ng fails with Cannot find module @angular/cli/bin/ng
Cannot find module '@angular/cli/bin/ng'
The ng command is the entry point to the Angular CLI package.
2 causes, each with a fixBack end
Angular app shows 'Cannot GET /' when served by a Node.js server
Cannot GET /dashboard
Cannot GET / is Express saying no route or file matches the request.
3 causes, each with a fixBack 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 fixBack end
Angular build says it cannot resolve '@angular/localize/init'
Can't resolve '@angular/localize/init' in '/usr/src/app/src'
The build imports @angular/localize, and that package is not in node_modules.
2 causes, each with a fixBack end
The command npm run build -- --prod exited with code 1 (Angular)
The command "npm run build -- --prod" exited with code 1
Exit code 1 only says the build failed; the real message is above it.
2 causes, each with a fix