Diagnosing WebSocket Connection Drops in Production Node.js Apps

Your WebSocket connections are dropping in production, but everything looks fine locally. Users are seeing disconnects after a few minutes of inactivity, or mid-session without any clear pattern. The server logs show nothing. This is a classic production-only problem, and it almost always has a concrete, fixable cause.

What you'll learn

• The most common reasons WebSocket connections drop in Node.js production environments
• How to use ping/pong heartbeats to keep connections alive and detect dead ones
• How load balancers and reverse proxies silently kill idle connections
• How to add structured logging so you can actually see what's happening
• A reconnection strategy on the client side that handles real-world network conditions

Prerequisites

This guide assumes you're running a Node.js server (v16 or later) using either the ws library or the built-in net module, and that your app is deployed behind a reverse proxy such as Nginx, an AWS Application Load Balancer, or a similar setup. Basic familiarity with WebSockets and async JavaScript is expected.

Why WebSocket Connections Drop

Before you start patching things, it's worth understanding the three main categories of drops you'll see in production.

Idle timeout from a proxy or load balancer. Most reverse proxies and cloud load balancers have an idle connection timeout — typically somewhere between 30 seconds and a few minutes. If no data flows over the WebSocket in that window, the proxy closes the TCP connection silently. Your server and client may not even notice immediately.

Application-level errors or unhandled exceptions. An uncaught error in a message handler can crash the connection without a clean close frame. If you're not listening for the error event on the socket, Node.js will emit an unhandled error and potentially crash the process.

Client network interruptions. Mobile clients, laptops switching between Wi-Fi and cellular, and VPN reconnects all cause TCP drops that the server won't detect immediately without a heartbeat mechanism.

Setting Up Structured Logging First

You can't diagnose what you can't see. Before anything else, add proper logging around connection lifecycle events. Here's a minimal example using the ws library:

const WebSocket = require('ws');
const wss = new WebSocket.Server({ port: 8080 });

wss.on('connection', (ws, req) => {
  const clientId = req.headers['x-forwarded-for'] || req.socket.remoteAddress;
  console.log(JSON.stringify({ event: 'connect', clientId, time: Date.now() }));

  ws.on('close', (code, reason) => {
    console.log(JSON.stringify({
      event: 'close',
      clientId,
      code,
      reason: reason.toString(),
      time: Date.now()
    }));
  });

  ws.on('error', (err) => {
    console.error(JSON.stringify({
      event: 'error',
      clientId,
      message: err.message,
      time: Date.now()
    }));
  });
});

Log the close code. A code of 1001 means the endpoint is going away. A code of 1006 means abnormal closure — no close frame was received at all, which is the fingerprint of a proxy timeout or a network drop. Once you see 1006 appearing consistently, you know you're dealing with an infrastructure-level cut rather than an application error.

Implementing Ping/Pong Heartbeats

The WebSocket protocol has a built-in heartbeat mechanism: ping and pong frames. Your server sends a ping, and a healthy client responds with a pong. If no pong arrives within a reasonable window, the connection is dead and you should terminate it explicitly.

const HEARTBEAT_INTERVAL = 30000; // 30 seconds
const PONG_TIMEOUT = 10000;       // 10 seconds to respond

wss.on('connection', (ws) => {
  ws.isAlive = true;

  ws.on('pong', () => {
    ws.isAlive = true;
  });

  const heartbeat = setInterval(() => {
    if (!ws.isAlive) {
      console.log(JSON.stringify({ event: 'terminate_dead', time: Date.now() }));
      clearInterval(heartbeat);
      return ws.terminate();
    }

    ws.isAlive = false;
    ws.ping();
  }, HEARTBEAT_INTERVAL);

  ws.on('close', () => {
    clearInterval(heartbeat);
  });
});

The pattern here is deliberate: you set isAlive to false before sending the ping, then flip it back to true only when a pong arrives. If the next interval fires and isAlive is still false, the connection is gone. Calling ws.terminate() instead of ws.close() destroys the underlying TCP socket immediately, which cleans up the file descriptor on your server.

Set your ping interval to less than your proxy's idle timeout. If your AWS ALB has a 60-second idle timeout, ping every 30 seconds to be safe.

Configuring Your Reverse Proxy

Nginx requires explicit configuration to support WebSocket upgrades and to increase idle timeouts. Without it, the default proxy_read_timeout of 60 seconds will kill your connections.

location /ws {
    proxy_pass http://localhost:8080;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "Upgrade";
    proxy_set_header Host $host;
    proxy_read_timeout 3600s;
    proxy_send_timeout 3600s;
}

The Upgrade and Connection headers are required for the HTTP-to-WebSocket handshake to succeed. Without them, Nginx treats the connection as plain HTTP and it will fail or behave unpredictably. Setting proxy_read_timeout to an hour (or whatever makes sense for your use case) prevents Nginx from cutting the connection during legitimate inactivity.

For AWS Application Load Balancers, the idle timeout is configured in the ALB settings under "Attributes". The default is 60 seconds; increase it to match your expected session length.

Handling the Error Event Properly

In Node.js, if you attach a 'connection' handler but not an 'error' handler on each individual socket, an error on that socket will bubble up as an unhandled 'error' event. If nothing is listening for it on the process level, Node.js will throw and potentially crash.

ws.on('error', (err) => {
  // Log it, don't rethrow it
  console.error(JSON.stringify({
    event: 'socket_error',
    message: err.message,
    code: err.code,
    time: Date.now()
  }));
});

You should also add a process-level safety net, but treat it as a last resort, not a primary handler:

process.on('uncaughtException', (err) => {
  console.error('Uncaught exception:', err.message);
  // Optionally restart the process via a process manager like PM2
});

Running your Node.js app under PM2 or a similar process manager means that even if the process crashes, it restarts automatically. That doesn't fix the bug, but it limits the blast radius while you investigate.

Client-Side Reconnection Logic

The server side is only half the picture. Your client needs to handle disconnects gracefully and reconnect without requiring a page reload. A simple exponential backoff strategy covers most real-world scenarios:

function connectWebSocket(url) {
  let ws;
  let retryDelay = 1000;
  const MAX_DELAY = 30000;

  function connect() {
    ws = new WebSocket(url);

    ws.addEventListener('open', () => {
      console.log('WebSocket connected');
      retryDelay = 1000; // reset on successful connection
    });

    ws.addEventListener('message', (event) => {
      handleMessage(JSON.parse(event.data));
    });

    ws.addEventListener('close', (event) => {
      console.warn(`WebSocket closed: code=${event.code}, wasClean=${event.wasClean}`);
      scheduleReconnect();
    });

    ws.addEventListener('error', (err) => {
      console.error('WebSocket error', err);
      // 'close' fires after 'error', so reconnect logic lives there
    });
  }

  function scheduleReconnect() {
    const jitter = Math.random() * 500;
    setTimeout(connect, retryDelay + jitter);
    retryDelay = Math.min(retryDelay * 2, MAX_DELAY);
  }

  connect();
  return () => ws && ws.close(); // return a cleanup function
}

The jitter term (a small random offset) is important when you have many clients. Without it, all clients that got disconnected at the same time will attempt to reconnect simultaneously, creating a thundering herd that spikes your server load right when you least want it.

Common Pitfalls

Forgetting to clear heartbeat intervals on close

If you don't clear the setInterval when a socket closes, it keeps firing on a dead socket. Over time, you accumulate hundreds of orphaned intervals that call ws.ping() on sockets that no longer exist. This is a slow memory and CPU leak. Always pair every setInterval with a clearInterval in the 'close' handler.

Using ws.close() instead of ws.terminate() for dead connections

ws.close() attempts a graceful shutdown by sending a close frame. If the underlying TCP connection is already dead, that close frame never arrives and the socket hangs in a closing state indefinitely. Use ws.terminate() when you've determined the connection is dead via a missed pong.

Not accounting for HTTP/2 or HTTPS termination

If your proxy terminates TLS and forwards plain HTTP to Node.js, make sure the Upgrade header is forwarded correctly. Some configurations strip it. Test with a tool like wscat to verify the full handshake succeeds end-to-end through your proxy stack, not just directly to the Node.js port.

Assuming code 1006 means a bug in your code

Code 1006 (abnormal closure) almost always means the TCP layer was cut by something outside your application: a proxy timeout, a firewall, a client network change. Don't spend hours looking at your message handlers if you're seeing consistent 1006 drops at a predictable interval — check your proxy timeout settings first.

Wrapping Up

Connection drops in production WebSocket apps are almost always caused by one of a small set of culprits. Here are the concrete steps to take after reading this:

1. Add structured logging for connect, close (with code), and error events. Deploy it and watch what close codes you're actually getting.
2. Implement server-side ping/pong with an interval shorter than your proxy's idle timeout. Clean up the interval on close.
3. Check your proxy configuration. Verify that Upgrade and Connection headers are forwarded and that idle timeouts are set appropriately for your use case.
4. Add client-side reconnection with exponential backoff and jitter so users recover automatically from transient drops.
5. Test through the full proxy stack using a tool like wscat to confirm end-to-end behavior before declaring the fix done.