The browser cannot open the WebSocket: connection refused
WebSocket connection to 'ws://localhost:8080/' failed: Error in connection establishment: net::ERR_CONNECTION_REFUSEDShort 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.
Fix it fast
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'2Match what you see, then jump to its fix
What does the error look like?
WebSocket connection to 'ws://localhost:8080/' failed: Error in connection establishment: net::ERR_CONNECTION_REFUSEDconnect 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/null2Fix
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
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
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
Back end
Application Load Balancer returns 502 for a Node.js target
HTTPCode_ELB_502_Count
An ALB returns 502 when the target gives it something it cannot use: a refused or reset connection, a connection closed mid-request, a bad response, or a header over 32 K.
4 causes, each with a fixBack end
corepack enable fails: permission denied while creating the pnpm link
Internal Error: EACCES: permission denied, symlink '../lib/node_modules/corepack/dist/pnpm.js' -> '/usr/local/bin/pnpm'
corepack enable writes small link files for yarn and pnpm next to your node binary.
2 causes, each with a fixBack end
Create React App says Node is too old, and npm will not run on the new one
npm does not support Node.js v10.19.0
The shell is running an old Node.js that is below the version Create React App needs.
3 causes, each with a fixBack end
firebase deploy cannot load your functions: user code failed to load
Functions codebase could not be analyzed successfully. It may have a syntax or runtime error
The Firebase CLI loads your functions code on your machine before it deploys, to learn which functions exist.
4 causes, each with a fixBack end
firebase deploy stops because the predeploy lint step failed
Error: There was an error deploying functions
The predeploy hook in firebase.json runs npm run lint before every deploy, and a failing hook cancels the deploy.
3 causes, each with a fixBack end
fluent-ffmpeg cannot find the ffmpeg or ffprobe binary
Error: Cannot find ffprobe
fluent-ffmpeg does not bundle ffmpeg.
4 causes, each with a fix