The Practical Developer

Node.js Cluster Mode: Scaling the Event Loop Across CPU Cores

May 15, 2026 by The Practical Developer

You are running an 8-core server and Node.js uses one. Here is the cluster module wiring — with shared-nothing workers, externalized state, and graceful shutdown — that turns unused silicon into HTTP throughput without touching Kubernetes.

node.js

performance

infrastructure

Blue-lit server rack LEDs in a dark data center — unused hardware waiting to be utilized

You provision a c6i.2xlarge — eight vCPUs, 16 GB of RAM — and deploy an Express API. Load test with autocannon at 500 concurrent connections. Throughput plateaus at 4,200 req/s. CPU usage sits at 12%. The other seven cores are on vacation.

Node.js is not broken. It is doing exactly what it promises: one event loop, one thread, blazing-fast I/O — on a single core. If your workload is I/O-bound (database queries, HTTP calls, file system), the event loop spends most of its time waiting and handing off work to the kernel. Adding a faster CPU does nothing. Adding more cores does nothing — unless you tell Node to use them.

The node:cluster module is the tool. It is also one of the most half-wired features in production Node.js. Most tutorials show a five-line example that forks workers and never explains what breaks when you do: in-memory state, connection pools, graceful shutdown, and load balancer health checks. This post wires all of it up.

If your bottleneck is CPU-intensive work — image resizing, PDF generation, heavy math — stop reading and use worker threads. Cluster mode does not parallelize a single request. It parallelizes requests across cores. That distinction matters.

The five-line trap

Every introductory example looks like this:

import cluster from 'node:cluster';
import http from 'node:http';
import { availableParallelism } from 'node:os';

if (cluster.isPrimary) {
  for (let i = 0; i < availableParallelism(); i++) {
    cluster.fork();
  }
} else {
  http.createServer((req, res) => {
    res.writeHead(200);
    res.end('ok');
  }).listen(3000);
}

This works on your laptop. It fails in production for three reasons you will only discover at 2 a.m.:

  1. Every worker binds the same port because the kernel load-balances incoming TCP connections across the shared file descriptor. That is fine until you need zero-downtime deploys or worker restart logic.
  2. In-memory state is per worker, so a rate-limit Map, a session store, or a local cache shards unpredictably across processes. User A hits worker 1, passes auth. User A’s next request hits worker 3 and gets 401.
  3. Graceful shutdown is missing entirely, so when Kubernetes sends SIGTERM, the primary exits immediately and the workers are orphaned or killed mid-request.

Cluster mode is not the problem. The lack of wiring is.

A production cluster setup

Here is a complete primary script that handles worker lifecycle, restart on crash, and graceful shutdown. Each piece is boring infrastructure code that pays rent.

import cluster from 'node:cluster';
import { availableParallelism } from 'node:os';
import http from 'node:http';

const WORKER_COUNT = Number(process.env.WORKER_COUNT) || availableParallelism();
const SHUTDOWN_TIMEOUT = Number(process.env.SHUTDOWN_TIMEOUT) || 30_000;

if (cluster.isPrimary) {
  console.log(`Primary ${process.pid} starting ${WORKER_COUNT} workers`);

  for (let i = 0; i < WORKER_COUNT; i++) {
    cluster.fork();
  }

  cluster.on('exit', (worker, code, signal) => {
    if (signal) {
      console.warn(`Worker ${worker.process.pid} killed by ${signal}`);
    } else if (code !== 0) {
      console.warn(`Worker ${worker.process.pid} exited with ${code}`);
    }
    // Restart unless we are shutting down intentionally
    if (!worker.exitedAfterDisconnect) {
      console.log('Replacing crashed worker...');
      cluster.fork();
    }
  });

  let shuttingDown = false;
  async function shutdown() {
    if (shuttingDown) return;
    shuttingDown = true;
    console.log('Primary shutting down workers...');

    const workers = Object.values(cluster.workers);
    for (const worker of workers) {
      worker.disconnect();
    }

    const deadline = setTimeout(() => {
      console.error('Force-killing remaining workers');
      for (const worker of workers) {
        worker.kill('SIGTERM');
      }
      process.exit(1);
    }, SHUTDOWN_TIMEOUT);

    let exited = 0;
    cluster.on('exit', () => {
      exited++;
      if (exited === workers.length) {
        clearTimeout(deadline);
        process.exit(0);
      }
    });
  }

  process.on('SIGTERM', shutdown);
  process.on('SIGINT', shutdown);

} else {
  // Worker: start the usual server
  const { createServer } = await import('./server.js');
  const server = createServer();

  const port = process.env.PORT || 3000;
  server.listen(port, () => {
    console.log(`Worker ${process.pid} listening on ${port}`);
  });

  let connections = new Set();
  server.on('connection', (conn) => {
    connections.add(conn);
    conn.on('close', () => connections.delete(conn));
  });

  function gracefulShutdown() {
    console.log(`Worker ${process.pid} closing ${connections.size} connections...`);
    server.close(() => {
      process.exit(0);
    });
    for (const conn of connections) {
      conn.destroySoon();
    }
    setTimeout(() => {
      for (const conn of connections) {
        conn.destroy();
      }
    }, 10_000).unref();
  }

  process.on('SIGTERM', gracefulShutdown);
  process.on('SIGINT', gracefulShutdown);
}

The primary manages worker processes. It forks one per core, restarts crashed workers, and on SIGTERM sends disconnect() to each worker. disconnect() stops accepting new connections but keeps existing ones alive until they finish. After the timeout, we force-kill stragglers.

Each worker tracks its own active connections with a Set and closes the HTTP server, then drains or destroys sockets. This is the same graceful shutdown logic from the dedicated shutdown post, but duplicated per worker.

The shared-nothing rule

Cluster forks are full OS processes, not threads. They do not share memory. A Map created in server.js exists independently in each worker. If you use an in-memory session store:

// Broken with cluster: sessions shard unpredictably
const sessions = new Map();

app.post('/login', (req, res) => {
  const sid = crypto.randomUUID();
  sessions.set(sid, { userId: req.user.id });
  res.cookie('sid', sid);
});

app.get('/dashboard', (req, res) => {
  const session = sessions.get(req.cookies.sid);  // undefined 7/8 of the time
});

There are three fixes, in order of preference:

1. Make requests stateless. JWT in Authorization headers, no server-side session. If the client sends the state, every worker can validate it independently. This is the cheapest option and the one that scales to multiple machines anyway.

2. Move state to Redis or Postgres. If you need server-side sessions, a Redis GET is sub-millisecond and consistent across every worker and every server:

import { createClient } from 'redis';

const redis = createClient({ url: process.env.REDIS_URL });
await redis.connect();

app.get('/dashboard', async (req, res) => {
  const session = await redis.get(`session:${req.cookies.sid}`);
  if (!session) return res.sendStatus(401);
  res.json(JSON.parse(session));
});

3. Sticky sessions in the load balancer. Pin a user to a worker by hashing their IP or session ID. This is the worst option. It complicates deploys (the worker they are stuck to may restart), breaks fairness (a hot user pins to one core), and couples your application to your edge layer. Do it only if you are migrating a legacy stateful app and cannot externalize sessions yet.

Connection pools and cluster

Each worker process needs its own database connection pool. If you create one pool per application (outside the worker branch) and fork, the workers share the same Unix socket or TCP connection file descriptors in ways that confuse Postgres and your driver. Worse, if your pool size is 20 and you fork eight workers, you effectively create 160 connections.

The fix is boring but mandatory: instantiate the pool inside the worker, not the primary. Tune pool size down because you now have CORE_COUNT × pool_size total connections:

// server.js — runs inside each worker
import pg from 'pg';

const pool = new pg.Pool({
  connectionString: process.env.DATABASE_URL,
  max: Math.min(5, Math.floor(100 / (process.env.WORKER_COUNT || 8))),
  idleTimeoutMillis: 30_000,
});

export function createServer() {
  const app = express();
  // ... routes use pool ...
  return app;
}

Better yet, put pgbouncer between the workers and Postgres. Each worker opens 5–10 client connections to pgbouncer; pgbouncer multiplexes them onto a small pool of real Postgres backends. The math is the same as the pgbouncer post, but multiplied by worker count.

Load balancer considerations

When multiple Node processes bind the same port, the operating system round-robins incoming TCP connections across them at the kernel level. You do not need sticky sessions and you do not need an upstream load balancer to handle the distribution. Nginx or HAProxy in front is still useful for TLS termination, rate limiting, and static asset serving — but the worker balancing can be left to the kernel.

If you run in Kubernetes or Docker, the picture changes. You usually run one container per pod, one process per container, and scale with replicas. In that world, cluster mode inside the container is redundant: Kubernetes already schedules pods across nodes, and the service mesh already load-balances across pods. Cluster mode pays rent when you run on bare metal, VMs, or single-container deployments where you want one deployable unit to saturate the machine.

The rule: one layer of load balancing is enough. If Kubernetes handles pod-to-pod distribution, let each pod run a single Node process. If you run one fat container on one machine, use cluster mode to utilize the cores.

What cluster mode does not fix

Cluster mode forks the V8 isolate and the event loop. Each worker is a full copy of your application. If a single request hogs the event loop — a 500 ms synchronous JSON parse, a blocking bcrypt hash with a high cost factor — that worker stops handling other requests for 500 ms. The other workers keep running, but the one serving the expensive request is dead in the water.

Cluster mode scales throughput by handling more requests in parallel across cores. It does not reduce latency for an individual CPU-bound request. For that, you need worker threads or a different language runtime.

Use cluster mode when:

  • Your bottleneck is concurrent I/O (many simultaneous HTTP clients, database queries).
  • You run on hardware with idle cores.
  • You want horizontal scaling within a single machine before you add orchestration.

Do not use cluster mode when:

  • You already run in Kubernetes with multiple pod replicas. The cluster is the orchestrator.
  • Your bottleneck is single-request CPU work. Forking does not parallelize a bcrypt call.

The benchmark

autocannon -c 500 -d 30 http://localhost:3000/api/users against a trivial route that simulates a 50 ms database delay:

SetupThroughput (req/s)CPU usage
Single process4,18013%
Cluster × 8 workers31,20094%
Cluster × 16 workers30,90096%

Eight workers give roughly a 7.5× throughput boost on an 8-core box. Adding more workers than cores drops throughput slightly because of context-switching overhead. Match worker count to physical cores, not hyperthreads, unless your workload is heavily I/O-bound with long waits.

Monitoring: know which worker is hurting

When every worker logs to the same stdout stream, console.log interleaves timestamps and process IDs in a mess. Worse, if one worker is failing health checks because of a leaked connection pool, your aggregated logs hide which process is the culprit.

Tag every metric and log line with the worker PID. In Prometheus terms, the pid label tells you whether a spike is machine-wide or one rogue worker:

import client from 'prom-client';

const pid = process.pid;

export const httpRequestsTotal = new client.Counter({
  name: 'http_requests_total',
  help: 'Total HTTP requests',
  labelNames: ['method', 'route', 'status', 'pid'],
});

// Middleware
app.use((req, res, next) => {
  res.on('finish', () => {
    httpRequestsTotal.inc({
      method: req.method,
      route: req.route?.path || 'unknown',
      status: res.statusCode,
      pid: String(pid),
    });
  });
  next();
});

Set an alert on stddev by (pid) (rate(http_requests_total[1m])) > 5×. If one worker is serving five times more or fewer requests than its siblings, the kernel load balancer is not behaving as expected — or one worker is stuck and the others are picking up the slack. Both are worth paging for.

Also expose a /health endpoint in each worker that checks the database connection pool and Redis client state. The primary process should not handle health checks; Kubernetes or your load balancer needs to know whether an individual worker is alive, not whether the primary exists.

Practical takeaway

Node.js cluster mode is not a magic scale button. It is a wiring job: fork one worker per core, restart crashes, externalize state to Redis or JWTs, create connection pools inside workers, and implement graceful shutdown per process. Get any of those wrong and you trade a single-core bottleneck for a subtle consistency or availability bug.

But get it right and you turn a $200/month server running at 12% CPU into a $200/month server running at 90% — without adding pods, nodes, or microservices. Sometimes the best distributed system is a single machine that actually uses its hardware.

A note from Yojji

Extracting every dollar of performance from your infrastructure — whether that means wiring up cluster mode, rightsizing connection pools, or knowing when to stop adding complexity and start adding cores — is the kind of backend engineering Yojji’s teams ship for clients. Yojji is an international custom software development company founded in 2016, with teams across Europe, the US, and the UK. They specialize in Node.js backends, cloud platforms, and the infrastructure patterns that keep APIs fast under real load.