Socket.IO Not Connecting in Ludo Games — Complete Fix Guide

// Enable Socket.IO debug logging on the client
// Set localStorage.debug BEFORE importing socket.io-client
localStorage.setItem('debug', 'socket.io-client:*');

// Or use a wildcard to see all Socket.IO internal logging
localStorage.setItem('debug', 'socket.io-client:socket socket.io-client:manager socket.io-client:transport*');

// Now import Socket.IO — debug logs appear in the Console tab
import { io } from 'socket.io-client';

const socket = io('https://api.ludokingapi.site', {
  transports: ['websocket', 'polling'],
  reconnection: true,
  reconnectionAttempts: 10,
  timeout: 20000
});

// Log all connection events for Ludo game diagnostics
socket.on('connect', () => {
  console.log('[LudoSocket] Connected:', socket.id);
  console.log('[LudoSocket] Transport:', socket.io.engine.transport.name);
});

socket.on('connect_error', (err) => {
  console.error('[LudoSocket] Connect error:', err.message);
  console.error('[LudoSocket] Error type:', err.constructor.name);
  console.error('[LudoSocket] Error data:', err.data);
});

socket.on('disconnect', (reason) => {
  console.warn('[LudoSocket] Disconnected:', reason);
});

socket.on('reconnect_attempt', (attemptNumber) => {
  console.log('[LudoSocket] Reconnect attempt #', attemptNumber);
});

socket.on('reconnect_failed', () => {
  console.error('[LudoSocket] All reconnection attempts exhausted'萌);
  showConnectionError('Unable to connect to game server. Please check your internet connection.');
});

// Inspect the engine transport in real time
socket.on('upgrade', () => {
  console.log('[LudoSocket] Transport upgraded to:', socket.io.engine.transport.name);
});

// Enable Socket.IO debug logging on the Node.js server
// Set DEBUG environment variable before running the server
// Linux/macOS:
// DEBUG=socket.io:* node server.js
// Windows (cmd):
// set DEBUG=socket.io:* && node server.js
// Windows (PowerShell):
// $env:DEBUG="socket.io:*"; node server.js

// Or programmatically in the server entry point
process.env.DEBUG = 'socket.io:*';

import express from 'express';
import { createServer } from 'http';
import { Server } from 'socket.io';

const app = express();
const httpServer = createServer(app);

const io = new Server(httpServer, {
  cors: {
    origin: ['https://your-ludo-app.com'],
    methods: ['GET', 'POST'],
    credentials: true
  },
  pingTimeout: 20000,    // Server waits 20s for pong before closing connection
  pingInterval: 25000,   // Ping every 25s to keep connection alive
  connectTimeout: 45000  // Initial connection timeout
});

io.on('connection', (socket) => {
  console.log('[Server] Client connected:', socket.id);
  console.log('[Server] Origin:', socket.handshake.headers.origin);
  console.log('[Server] Transport:', socket.conn.transport.name);

  socket.on('join_game', ({ gameId, playerId }) => {
    socket.join(`game_${gameId}`);
    console.log('[Server] Player', playerId, 'joined game', gameId);
    io.to(`game_${gameId}`).emit('player_joined', { playerId });
  });

  socket.on('disconnect', (reason) => {
    console.log('[Server] Client', socket.id, 'disconnected:', reason);
  });
});

httpServer.listen(3001, () => {
  console.log('[Server] Ludo Socket.IO server running on port 3001');
});

import { Server } from 'socket.io';

const allowedOrigins = [
  'http://localhost:3000',              // local development
  'https://ludo.yourapp.com',           // production domain
  'https://staging.yourapp.com',        // staging environment
  'https://m.ludo.yourapp.com'         // mobile subdomain
];

const io = new Server({
  cors: {
    origin: (origin, callback) => {
      // Allow requests with no origin (mobile apps, Postman, curl)
      if (!origin) return callback(null, true);
      if (allowedOrigins.includes(origin)) {
        return callback(null, true);
      }
      console.error('[CORS] Blocked origin:', origin);
      callback(new Error('Not allowed by CORS policy'));
    },
    methods: ['GET', 'POST'],
    credentials: true,
    allowedHeaders: ['Authorization', 'Content-Type', 'X-Game-Id', 'X-Player-Token']
  }
});

// Production tip: Use an environment variable for origins to avoid hardcoding
// const allowedOrigins = process.env.ALLOWED_ORIGINS?.split(',') || ['http://localhost:3000'];

import { io } from 'socket.io-client';

const socket = io('https://api.ludokingapi.site', {
  // Transport selection: WebSocket first, HTTP polling as fallback
  transports: ['websocket', 'polling'],

  // MUST match server's credentials: true setting
  withCredentials: true,

  // Reconnection: essential for mobile where connections drop frequently
  reconnection: true,
  reconnectionAttempts: 10,
  reconnectionDelay: 1000,
  reconnectionDelayMax: 8000,

  // Total timeout for initial connection attempt
  timeout: 20000
});

socket.on('connect', () => {
  console.log('[Ludo] Connected as', socket.id);
  socket.emit('ludo_join', { gameId: getGameId(), playerId: getPlayerId() });
});

socket.on('connect_error', (err) => {
  if (err.message.includes('CORS') || err.message.includes('not allowed')) {
    console.error('[Ludo] CORS error — verify server origin whitelist includes your domain');
  }
});

// Correct transport configuration for Ludo multiplayer
// WebSocket for low latency, polling fallback for proxy compatibility
const socket = io('https://api.ludokingapi.site', {
  transports: ['websocket', 'polling'], // always include BOTH
  upgrade: true,                      // upgrade to WS after polling succeeds
  rememberTransport: false,           // do not cache the failed transport
  transports: ['polling', 'websocket']  // polling-first for hostile networks
});

// Detect which transport is active and log it for debugging
socket.on('connect', () => {
  const transport = socket.io.engine.transport.name;
  console.log('[Ludo] Transport in use:', transport);
  if (transport === 'websocket') {
    console.log('[Ludo] Low-latency WebSocket active — optimal for real-time Ludo');
  } else {
    console.warn('[Ludo] HTTP polling active — higher latency, possible proxy interference');
  }
});

// Detect transport upgrades when the connection improves
socket.io.engine.on('upgrade', () => {
  const upgraded = socket.io.engine.transport.name;
  console.log('[Ludo] Transport upgraded to:', upgraded);
});

// Detect transport downgrades on connection instability
socket.io.engine.on('packet', (packet) => {
  if (packet.type === 'pong') {
    console.log('[Ludo] Heartbeat received — connection alive');
  }
});

// LudoSocketManager — production-grade Socket.IO manager with state recovery
class LudoSocketManager {
  constructor(gameId, playerId) {
    this.gameId      = gameId;
    this.playerId   = playerId;
    this.gameState  = null;
    this.lastTurn   = 0;
    this.isMyTurn   = false;

    this.socket = io('https://api.ludokingapi.site', {
      transports: ['websocket', 'polling'],
      withCredentials: true,
      reconnection: true,
      reconnectionAttempts: 20,
      reconnectionDelay: 1000,
      reconnectionDelayMax: 10000,
      reconnectionDelayGrowth: 1.5,
      timeout: 20000
    });

    this.setupEventHandlers();
  }

  setupEventHandlers() {
    this.socket.on('connect', () => {
      console.log('[LudoSocket] Reconnected as', this.socket.id);
      this.joinGame();
      this.recoverState();
    });

    this.socket.on('disconnect', (reason) => {
      console.warn('[LudoSocket] Disconnected:', reason);
      if (reason === 'io server disconnect') {
        // Server initiated the disconnect — do not auto-reconnect
        showError('Game ended by server');
      } else {
        // Network drop — show reconnecting status
        showConnectionStatus('Reconnecting...', 'warning');
      }
    });

    this.socket.on('reconnect_attempt', (attempt) => {
      console.log('[LudoSocket] Reconnect attempt', attempt);
      showConnectionStatus(`Reconnecting (attempt ${attempt})...`, 'info');
    });

    this.socket.on('reconnect_failed', () => {
      showError('Connection lost. Please refresh the page.');
    });

    // Receive full game state snapshot (used on reconnect)
    this.socket.on('state_snapshot', (state) => {
      this.gameState = state;
      this.lastTurn  = state.turn;
      this.renderBoard(state);
      console.log('[LudoSocket] Board synchronized — turn', state.turn);
    });

    // Receive incremental state updates (normal gameplay)
    this.socket.on('state_delta', (delta) => {
      this.gameState = applyDelta(this.gameState, delta);
      this.lastTurn = delta.turn;
      this.renderBoard(this.gameState);
    });

    this.socket.on('turn_change', ({ activePlayer, canRoll }) => {
      this.isMyTurn = (activePlayer === this.playerId);
      this.setTurnIndicator(this.isMyTurn, activePlayer);
    });

    this.socket.on('token_captured', ({ capturedBy, capturedToken }) => {
      this.playCaptureAnimation(capturedBy, capturedToken);
    });

    this.socket.on('game_over', ({ winner }) => {
      this.showGameOver(winner);
    });
  }

  joinGame() {
    this.socket.emit('join_game', {
      gameId: this.gameId,
      playerId: this.playerId
    });
  }

  recoverState() {
    // Request full state snapshot on reconnect to resync the board
    this.socket.emit('sync_request', {
      gameId: this.gameId,
      lastTurn: this.lastTurn
    });
  }

  emitMove(tokenIndex, pathIndex) {
    this.socket.emit('move_token', {
      gameId: this.gameId,
      playerId: this.playerId,
      tokenIndex,
      pathIndex,
      timestamp: Date.now()
    });
  }
}

# Check Socket.IO versions on both server and client
# Server (Node.js)
npm list socket.io
# Expected: socket.io@4.x.x (or socket.io@3.x.x)

# Client (browser or bundler)
npm list socket.io-client
# Must match server version exactly

# Install matching versions explicitly
# Server:
npm install socket.io@4.7.5
# Client:
npm install socket.io-client@4.7.5

# Nginx configuration for Socket.IO — WebSocket proxy setup
# Add to your server {} block in /etc/nginx/sites-available/ludo

location /socket.io/ {
  proxy_pass http://ludo_backend;

  # HTTP/1.1 is required for WebSocket upgrade — HTTP/1.0 does not support it
  proxy_http_version 1.1;

  # MANDATORY: These two headers enable WebSocket upgrade through Nginx
  proxy_set_header Upgrade $http_upgrade;
  proxy_set_header Connection "upgrade";

  proxy_set_header Host $host;
  proxy_set_header X-Real-IP $remote_addr;
  proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
  proxy_set_header X-Forwarded-Proto $scheme;

  # Disable buffering to prevent WebSocket frame delays during active gameplay
  proxy_buffering off;

  # Extended timeouts for Ludo game sessions that may be idle between turns
  proxy_read_timeout 86400;
  proxy_send_timeout 300;

  # Optional: increase body size for large state snapshots on reconnect
  proxy_buffer_size 128k;
  proxy_buffers 4 256k;
}

# Reload Nginx after making changes:
# sudo nginx -t && sudo systemctl reload nginx

// Mobile-optimized Socket.IO configuration for Ludo on cellular networks
// Detect mobile and apply aggressive reconnection settings
const isMobile = /Android|iPhone|iPad|iPod/i.test(navigator.userAgent);

const mobileConfig = isMobile ? {
  // Mobile networks often block WebSocket — use polling first on cellular
  transports: ['polling', 'websocket'],
  // Shorter ping interval to keep connection alive through carrier NAT
  pingInterval: 15000,
  pingTimeout: 10000,
  // Aggressive reconnection for unstable mobile networks
  reconnectionDelay: 500,
  reconnectionDelayMax: 5000
} : {
  // Desktop: prefer WebSocket for lowest latency
  transports: ['websocket', 'polling'],
  pingInterval: 25000,
  pingTimeout: 20000
};

const socket = io('https://api.ludokingapi.site', {
  ...mobileConfig,
  reconnection: true,
  reconnectionAttempts: 50,     // Keep trying on mobile — network may recover
  withCredentials: true,
  timeout: 30000
});

// Heartbeat monitoring to detect silent disconnects on mobile
socket.on('connect', () => {
  console.log('[Ludo] Mobile socket connected — transport:', socket.io.engine.transport.name);
  if (isMobile) {
    console.warn('[Ludo] Running on mobile — using mobile-optimized reconnection settings');
  }
});

// Listen for network status changes and reconnect when coming back online
window.addEventListener('online', () => {
  console.log('[Ludo] Network restored — attempting reconnection');
  if (!socket.connected) socket.connect();
});

window.addEventListener('offline', () => {
  console.warn('[Ludo] Network lost — queueing moves locally until reconnection');
});