Maaz Zindani

Loading the index…

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

Angular app gets ERR_CONNECTION_REFUSED from a local Node.js API

ErrorFailed to load resource: net::ERR_CONNECTION_REFUSED

Short answer

Nothing accepted the connection on the address the browser or dev server tried. Since Node.js 17 the name localhost may resolve to an IPv6 address first, so a server bound to IPv4 only refuses it. Bind the server to a clear address, or check the ng serve proxy target and restart it.

  • Applies to Node.js 22, Angular 20, Express 5
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Check what is listening on the API port, and on which address.

    sudo lsof -iTCP:3000 -sTCP:LISTEN -n -P
  2. 2Match what you see, then jump to its fix

    1. 1The server prints its start message, yet requests to localhost are refused while 127.0.0.1 workslocalhost resolves to IPv6 but the server listens on IPv4 onlyFix
    2. 2The ECONNREFUSED message appears in the ng serve terminal, not only in the browserThe ng serve proxy points at the wrong targetFix

What does the error look like?

  • Failed to load resource: net::ERR_CONNECTION_REFUSED
  • ECONNREFUSED

Cause 1 of 2

localhost resolves to IPv6 but the server listens on IPv4 only

1Check

Node.js has returned DNS results in the order the resolver gives them (verbatim) since v17.0.0. If a name returns an IPv6 address first, a client connects to ::1. A server that was told to listen on 127.0.0.1 does not answer there.

curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:3000/
curl -s -o /dev/null -w "%{http_code}\n" "http://[::1]:3000/"

2Fix

Leave out the host so the server accepts connections on :: (and usually 0.0.0.0 as well), or make the client use the same explicit address. You can also change the lookup order for the Node.js client.

// server: no host argument
app.listen(3000);

// client-side Node.js code, if it must prefer IPv4
require('node:dns').setDefaultResultOrder('ipv4first');

3Verify

Both address checks from the previous step should now answer.

curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:3000/
curl -s -o /dev/null -w "%{http_code}\n" "http://[::1]:3000/"

Confirmed by nodejs.org

Did this fix it?

Cause 2 of 2

The ng serve proxy points at the wrong target

1Check

The proxy target in proxy.conf.json must match the host and port the API really uses. Changes to this file only apply after ng serve is restarted.

cat src/proxy.conf.json
grep -n "proxyConfig" angular.json

2Fix

Correct the target and restart ng serve.

{
  "/api/**": {
    "target": "http://localhost:3000",
    "secure": false
  }
}

3Verify

Restart the dev server and call the API through it.

curl -i http://localhost:4200/api/health

Confirmed by angular.dev

Did this fix it?

How do I stop it coming back?

  • Use one explicit API address in the app environment file and in the proxy config.
  • Print the address the server listens on at start-up, so mismatches are visible.
  • Restart ng serve after any change to the proxy file.

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

Next step

Want this handled for good?

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