When developing web applications, you might encounter connectivity issues between your client and server when using Socket.io on localhost.

For Eg.: A common error is ECONNREFUSED ::1:PORT, which indicates a problem connecting to the IPv6 loopback address.

This article explains Why, when you run client and server Socket.io on localhost, you may face issues connecting the client to the server despite both being on the same machine, and how to resolve it?

Understanding IPv4 and IPv6

IPv4 and IPv6 are Internet Protocol versions used to identify devices on a network.

IPv4: Uses a 32-bit address format (e.g., 127.0.0.1). It has been the foundation of IP addressing for many years.
IPv6: Uses a 128-bit address format (e.g., ::1). It was introduced to address the shortage of IPv4 addresses and to provide enhanced features.

Localhost addresses for these protocols are:
IPv4: 127.0.0.1
IPv6: ::1

The Issue: ECONNREFUSED ::1:3030
The ECONNREFUSED error indicates that the connection attempt was refused, often because no server is listening on the specified address and port. When this error mentions ::1:3030, it points to an issue with the IPv6 address ::1.

Why This Happens
When you start a server on localhost, it might be listening on the IPv4 address (127.0.0.1), but your client tries to connect using the IPv6 address (::1). If the server isn't configured to listen on both IPv4 and IPv6, the connection attempt to ::1 will be refused.

Resolving the Issue
To resolve this, you can force your client to use the IPv4 address explicitly or ensure your server listens on both IPv4 and IPv6.

Solution 1: Use IPv4 Explicitly

Modify your client code to use 127.0.0.1 instead of localhost.

Client Code Example:

const socket = io('http://127.0.0.1:3030', {
  reconnection: true,
  reconnectionAttempts: Infinity,
  reconnectionDelay: 1000,
  reconnectionDelayMax: 5000,
  randomizationFactor: 0.5,
  transports: ['websocket']
});

socket.on('connect', () => {
  console.log('Successfully connected to the server.');
});

socket.on('connect_error', (error) => {
  console.error('Connection failed:', error);
});

Solution 2: Ensure Server Listens on Both IPv4 and IPv6

Configure your server to listen on both IPv4 and IPv6 addresses.

Server Code Example:

const http = require('http');
const express = require('express');
const socketio = require('socket.io');

const app = express();
const server = http.createServer(app);
const io = socketio(server, {
  transports: ['websocket'],
  cors: {
    origin: "*",
    methods: ["GET", "POST"]
  }
});

// Basic route
app.get('/', (req, res) => {
  res.send('Hello World');
});

// Socket.io connection handler
io.on('connection', (socket) => {
  console.log('Client connected');
  socket.on('disconnect', () => {
    console.log('Client disconnected');
  });
});

// Start server
const PORT = process.env.PORT || 3030;
server.listen(PORT, '0.0.0.0', () => {
  console.log(`Server is running and Socket.io is listening on http://localhost:${PORT}`);
});

By binding the server to 0.0.0.0, it listens on all network interfaces, including both IPv4 and IPv6.

Conclusion

The ECONNREFUSED ::1:PORT error is a common issue when dealing with Socket.io on localhost.
By explicitly using the IPv4 address or ensuring your server listens on both IPv4 and IPv6, you can resolve this connectivity issue. Understanding the differences between IPv4 and IPv6 and their respective localhost addresses is crucial for troubleshooting and ensuring seamless communication between your client and server.