Socket.io Error Handling and Reconnection Reliable Real-Time Communication

Socket.io Error Handling and Reconnection

Socket.io provides built-in reconnection, but you need to handle errors and edge cases properly. This guide covers best practices.

Built-in Reconnection

Socket.io automatically reconnects when the connection drops:

// Client
const socket = io(URL, {
  reconnection: true,          // Enable reconnection (default: true)
  reconnectionAttempts: 10,    // Max attempts (default: Infinity)
  reconnectionDelay: 1000,     // Initial delay (default: 1000ms)
  reconnectionDelayMax: 5000,  // Max delay (default: 5000ms)
  randomizationFactor: 0.5     // Randomize delay (default: 0.5)
});

socket.on("connect", () => {
  console.log("Connected");
});

socket.on("disconnect", (reason) => {
  console.log("Disconnected:", reason);
  // Socket.io will auto-reconnect (unless reason is "io server disconnect")
});

socket.on("reconnect", (attempt) => {
  console.log("Reconnected after", attempt, "attempts");
});

socket.on("reconnect_error", (err) => {
  console.error("Reconnection error:", err);
});

socket.on("reconnect_failed", () => {
  console.error("Failed to reconnect after max attempts");
});

Disconnect Reasons

Handling Server-Side Disconnects

// Server: disconnect a specific client
io.on("connection", (socket) => {
  socket.on("kick", ({ userId }) => {
    const targetSocket = onlineUsers.get(userId);
    if (targetSocket) {
      io.sockets.sockets.get(targetSocket)?.disconnect(true);
      // true = close the underlying connection (no reconnection)
    }
  });
});

Rejoin Rooms on Reconnection

When a client reconnects, they get a new socket ID and lose all room memberships. Rejoin automatically:

// Client: store active chat and rejoin on reconnect
let activeChats = [];

socket.on("connect", () => {
  // Rejoin all active chats
  activeChats.forEach((targetUserId) => {
    socket.emit("join:chat", { targetUserId });
  });
});

// When joining a chat, add to active list
const joinChat = (targetUserId) => {
  activeChats.push(targetUserId);
  socket.emit("join:chat", { targetUserId });
};

Server-Side Error Handling

io.on("connection", (socket) => {
  socket.on("error", (err) => {
    console.error("Socket error:", err);
    // Notify the client
    socket.emit("error", { message: "Internal server error" });
  });
  
  socket.on("message:send", async (data, callback) => {
    try {
      const message = await Message.create({
        senderId: socket.userId,
        receiverId: data.targetUserId,
        text: data.text
      });
      
      // Acknowledgment: success
      callback({ success: true, message });
      
      // Broadcast
      const roomId = getRoomId(socket.userId, data.targetUserId);
      io.to(roomId).emit("message:received", message);
    } catch (err) {
      // Acknowledgment: error
      callback({ success: false, error: err.message });
    }
  });
});

Using Acknowledgments

Acknowledgments confirm the server received and processed the event:

// Client
socket.emit("message:send", { targetUserId, text }, (response) => {
  if (response.success) {
    console.log("Message sent:", response.message);
  } else {
    console.error("Failed:", response.error);
  }
});

// Server
socket.on("message:send", (data, callback) => {
  // callback is the acknowledgment function
  try {
    // ... process ...
    callback({ success: true });
  } catch (err) {
    callback({ success: false, error: err.message });
  }
});

Offline Message Queue

When the client is disconnected, queue messages and send on reconnect:

// Client
const messageQueue = [];
let isConnected = false;

socket.on("connect", () => {
  isConnected = true;
  // Send queued messages
  while (messageQueue.length > 0) {
    const msg = messageQueue.shift();
    socket.emit("message:send", msg, (response) => {
      if (!response.success) {
        messageQueue.unshift(msg); // Re-queue on failure
      }
    });
  }
});

socket.on("disconnect", () => {
  isConnected = false;
});

const sendMessage = (data) => {
  if (isConnected) {
    socket.emit("message:send", data);
  } else {
    messageQueue.push(data);
    console.log("Message queued (offline)");
  }
};

The Takeaway

Socket.io error handling involves: leveraging built-in reconnection (configurable attempts, delays), handling disconnect reasons (some auto-reconnect, some don't), rejoining rooms on reconnect, using acknowledgments for confirmed delivery, handling server-side errors with try-catch, and queueing messages when offline. Use acknowledgments (callback functions) to confirm the server processed each event successfully.