Maaz Zindani

Loading the index…

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

The browser cannot open the WebSocket: connection refused

ErrorWebSocket connection to 'ws://localhost:8080/' failed: Error in connection establishment: net::ERR_CONNECTION_REFUSED

Short answer

ERR_CONNECTION_REFUSED means nothing accepted the TCP connection at the address and port the client dialled. It is not a WebSocket protocol error. Check that the server process runs, that it listens on that exact port, and that its bind address matches where the client connects from.

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

Fix it fast

  1. 1Find out which cause you have

    Ask the machine which ports have a listener. If your port is missing, the client is not the problem.

    sudo ss -ltnp | grep -E ':8080|node'
  2. 2Match what you see, then jump to its fix

    1. 1ss shows no listener on the port in the ws:// URLThe server is not running or listens on another portFix
    2. 2A listener exists, yet connections from another machine or container are refusedThe server listens on a different address than the client dialsFix

What does the error look like?

  • WebSocket connection to 'ws://localhost:8080/' failed: Error in connection establishment: net::ERR_CONNECTION_REFUSED
  • connect ECONNREFUSED 127.0.0.1:8080

Cause 1 of 2

The server is not running or listens on another port

1Check

Compare the port in the client URL with the one in the server's listen call, and read the server log for a crash at start.

grep -rn "listen(" src/ server.js 2>/dev/null
grep -rn "new WebSocket" src/ public/ 2>/dev/null

2Fix

Start the server and make both sides use the same port. Reading it from one environment variable keeps them in step.

const PORT = process.env.PORT || 8080;
server.listen(PORT);

3Verify

A listener appears on the port.

sudo ss -ltn | grep ':8080'

Confirmed by nodejs.org

Did this fix it?

Cause 2 of 2

The server listens on a different address than the client dials

1Check

When host is omitted, Node.js accepts connections on all addresses (:: or 0.0.0.0). A server started with an explicit host such as 127.0.0.1 answers only on that one.

sudo ss -ltn | grep ':8080'

2Fix

Bind to the address the client really uses. For a server reached from other hosts or from outside a container, leave host out or use 0.0.0.0.

// reachable from other machines
server.listen(8080, '0.0.0.0');

3Verify

From the client machine, open a TCP connection to the host and port.

curl -i http://SERVER_HOST:8080/

Confirmed by nodejs.org

Did this fix it?

How do I stop it coming back?

  • Put the WebSocket URL in one config value, not in several files.
  • Log the listening address and port at start so a wrong bind is visible.
  • Run the server under a process manager that restarts it after a crash.

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.