ECONNREFUSED in Node.js while other clients connect fine
Error: connect ECONNREFUSEDShort answer
ECONNREFUSED means the machine answered and refused the connection. If curl works but Node.js fails, the two clients are not connecting the same way: Node may pick an IPv6 address your server does not listen on, or it ignores the proxy settings that curl reads from the environment. Compare the address and the proxy first.
Fix it fast
1Find out which cause you have
Print the address Node.js got for the host name and the full error. The address in the message shows which of the causes applies.
node -e "require('node:dns').lookup('localhost',{all:true},(e,a)=>console.log(e||a))"2Match what you see, then jump to its fix
- 1
the address after ECONNREFUSED in the message is ::1localhost resolves to ::1 but the server listens on IPv4 onlyFix - 2
ECONNREFUSED with the same message from curl when you use the exact host and port Node.js usesNothing is listening on that port, or it is the wrong portFix - 3
The URL is an outside address, curl works on a network that needs HTTP_PROXY or HTTPS_PROXY, and Node.js is refusedcurl goes through a proxy from the environment, Node.js connects directlyFix
- 1
What does the error look like?
Error: connect ECONNREFUSEDECONNREFUSED
Cause 1 of 3
localhost resolves to ::1 but the server listens on IPv4 only
1Check
Since Node.js 17, dns.lookup returns addresses in the order the resolver gives them, with no IPv4 first sorting. If the list starts with ::1 and your server is bound to 127.0.0.1, the connection is refused. Node.js 20 and later also try the next address by default, so this is most common on older runtimes or with autoSelectFamily turned off.
node -e "require('node:dns').lookup('localhost',{all:true},(e,a)=>console.log(a))"
node -p "process.version"2Fix
Use the literal address in the URL, or make Node.js prefer IPv4 for the whole process.
// option 1: be explicit
const url = 'http://127.0.0.1:3000/health';
// option 2: at the top of your entry file
require('node:dns').setDefaultResultOrder('ipv4first');3Verify
Run the request again. The error should be gone and the response should arrive.
node client.jsConfirmed by nodejs.org
Cause 2 of 3
Nothing is listening on that port, or it is the wrong port
1Check
Node.js describes ECONNREFUSED as a connection refused by the target, usually because the service is not active there. Repeat the request with the exact host and port from the error line.
curl -v http://127.0.0.1:3000/
sudo ss -ltnp2Fix
Start the server, or correct the port in the code or environment variable that builds the URL. A hard-coded port in one file and a different one in the server's config is the usual mismatch.
const port = process.env.API_PORT ?? 3000;
const url = `http://127.0.0.1:${port}/health`;
console.log('calling', url);3Verify
The logged URL matches a port shown by ss, and curl to it succeeds.
curl -I http://127.0.0.1:3000/Confirmed by nodejs.org
Cause 3 of 3
curl goes through a proxy from the environment, Node.js connects directly
1Check
curl reads HTTP_PROXY and HTTPS_PROXY from the environment. Node.js only does so when NODE_USE_ENV_PROXY=1 or --use-env-proxy is set, a feature added in Node.js 24.5 and 22.21.
env | grep -i proxy
node -p "process.version"2Fix
Start Node.js with the proxy support switched on and list hosts that must bypass the proxy in NO_PROXY.
NODE_USE_ENV_PROXY=1 HTTP_PROXY=http://proxy.example.com:8080 NO_PROXY=localhost,127.0.0.1 node client.js3Verify
Run the same request. It should now travel through the proxy and return a response.
NODE_USE_ENV_PROXY=1 node client.jsConfirmed by nodejs.org
How do I stop it coming back?
- Use 127.0.0.1 instead of localhost in local URLs, and bind servers to the same address.
- Read host and port from one environment variable, and log the final URL at startup.
- Pin the Node.js version in .nvmrc or the engines field so the lookup and proxy behaviour is the same on every machine.
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