JavaScript WebSocket Cannot Connect to Localhost – How to Fix It

Written By: Nathan Kellert

Posted On:

In this article we are going to talk about JavaScript WebSocket Cannot Connect to Localhost. WebSockets are an awesome way to create real-time applications, allowing instant two-way communication between a client and a server. However, if you’re trying to connect a WebSocket to localhost and it’s not working, don’t worry—you’re not alone!

In this guide, we’ll go over why this happens and how to fix it quickly.

JavaScript WebSocket Cannot Connect to Localhost

Here are the most common issues that cause WebSocket connection failures on localhost:

  1. The WebSocket server is not running
  2. Incorrect WebSocket URL (ws:// or wss:// issue)
  3. Port conflicts or firewall blocking the connection
  4. Mixed content issue (HTTP vs HTTPS)
  5. CORS restrictions preventing the connection

Let’s go through each issue step by step and fix it!

1. Ensure the WebSocket Server Is Running

Before anything else, make sure your WebSocket server is actually running.

For example, if you’re using Node.js with ws, your server should look something like this:

const WebSocket = require('ws');

const server = new WebSocket.Server({ port: 8080 });

server.on('connection', (socket) => {
    console.log('Client connected');

    socket.on('message', (message) => {
        console.log(`Received: ${message}`);
    });

    socket.send('Hello from server!');
});

console.log('WebSocket server running on ws://localhost:8080');

Fix: If the server isn’t running, start it using:

node server.js

Then, try connecting again from your frontend.

2. Check the WebSocket URL

Your WebSocket client must use the correct URL to connect.

For example, in your frontend JavaScript:

const socket = new WebSocket('ws://localhost:8080');

If you’re using HTTPS, your WebSocket connection must use wss:// instead of ws://:

const socket = new WebSocket('wss://localhost:8080');

Fix:

  • Use ws:// for http://localhost.
  • Use wss:// for https://localhost.

3. Check Port Conflicts & Firewall Settings

If another process is already using port 8080, your WebSocket server won’t be able to start.

Fix:
Run this command to check if something is using port 8080:

netstat -an | grep 8080

If something is running, try changing the port in your WebSocket server:

const server = new WebSocket.Server({ port: 3000 });

Then update your frontend connection:

const socket = new WebSocket('ws://localhost:3000');

💡 Windows Firewall or Antivirus might block connections—try disabling them temporarily to see if it works.

4. Mixed Content Issue (HTTPS vs HTTP)

If your website runs on HTTPS, but your WebSocket uses ws://, most browsers will block the connection for security reasons.

Fix:

  • Use wss://localhost:8080 instead of ws:// when testing over HTTPS.
  • If you’re using Express, enable HTTPS with a self-signed certificate:
const https = require('https');
const fs = require('fs');
const WebSocket = require('ws');

const server = https.createServer({
    cert: fs.readFileSync('cert.pem'),
    key: fs.readFileSync('key.pem')
});

const wss = new WebSocket.Server({ server });

server.listen(8080, () => {
    console.log('Secure WebSocket server running on wss://localhost:8080');
});

5. CORS Restrictions (Cross-Origin Requests Blocked)

Sometimes, browsers block WebSocket connections due to security settings, especially if the frontend and backend are running on different ports.

Fix: Allow CORS in your WebSocket server:

server.on('connection', (socket, req) => {
    socket.send('CORS fixed!');
});

If you’re using Express.js with WebSockets, allow CORS like this:

const cors = require('cors');
app.use(cors());

Final Thoughts

If your WebSocket isn’t connecting to localhost, try these steps:

✔️ Ensure your WebSocket server is running
✔️ Use the correct WebSocket URL (ws:// or wss://)
✔️ Check for port conflicts and firewall settings
✔️ Fix HTTPS/HTTP mismatches
✔️ Handle CORS properly

Once you’ve fixed these, your WebSocket connection should work smoothly! 🚀

Still having trouble? Drop your error message in the comments, and I’ll help you out! 😊

Photo of author

Nathan Kellert

Nathan Kellert is a skilled coder with a passion for solving complex computer coding and technical issues. He leverages his expertise to create innovative solutions and troubleshoot challenges efficiently.

Leave a Comment