Maaz Zindani

Loading the index…

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

ECONNREFUSED in Node.js while other clients connect fine

ErrorError: connect ECONNREFUSED

Short 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.

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

Fix it fast

  1. 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))"
  2. 2Match what you see, then jump to its fix

    1. 1the address after ECONNREFUSED in the message is ::1localhost resolves to ::1 but the server listens on IPv4 onlyFix
    2. 2ECONNREFUSED 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. 3The 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

What does the error look like?

  • Error: connect ECONNREFUSED
  • ECONNREFUSED

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.js

Confirmed by nodejs.org

Did this fix it?

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 -ltnp

2Fix

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

Did this fix it?

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.js

3Verify

Run the same request. It should now travel through the proxy and return a response.

NODE_USE_ENV_PROXY=1 node client.js

Confirmed by nodejs.org

Did this fix it?

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 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.