The Node.js event loop, explained through the bugs it causes

What does the event loop actually do?

It repeatedly asks: is there work ready to run? The loop cycles through phases — timers (setTimeout callbacks whose time has come), pending I/O callbacks, poll (waiting for and processing new I/O), check (setImmediate), and close handlers. Between each callback it drains the microtask queue, where resolved promises live.

Your JavaScript runs on one thread throughout. Concurrency comes from the fact that waiting for a database or a file happens elsewhere — the OS or libuv's thread pool — and hands a callback back when it is done.

What does blocking look like in production?

Response times for every endpoint degrade at once, in proportion to the blocking work, even for endpoints that do nothing.

A report we debugged for a client: p50 latency was 40ms and p99 was 3.2 seconds across every route. The cause was one endpoint synchronously generating a PDF. While it ran, all other requests queued behind it — including the health check, which caused the orchestrator to restart healthy pods.

• Large JSON.parse or JSON.stringify — parsing a 10MB payload blocks for tens of milliseconds.
• Synchronous crypto: bcrypt with a high cost factor, or any *Sync method.
• Catastrophic backtracking in a regular expression run against user input.
• Image processing, PDF generation, CSV export in-process.
• Tight loops over large arrays: sorting 500,000 records to serve one request.

How do you detect it?

import { monitorEventLoopDelay } from "node:perf_hooks";

const histogram = monitorEventLoopDelay({ resolution: 20 });
histogram.enable();

setInterval(() => {
  const p99ms = histogram.percentile(99) / 1e6;
  if (p99ms > 100) logger.warn({ p99ms }, "event loop lag high");
  histogram.reset();
}, 30_000);

1. 1Export event loop lag to your metrics system and alert above ~100ms at p99.
2. 2Profile with --cpu-prof or a continuous profiler to find the offending function.
3. 3Load test with concurrency, not sequential requests — blocking is invisible at concurrency 1.
4. 4Watch for correlation: if all endpoints slow together, suspect the loop rather than a database.

How do you fix blocking work?

1. 1Move it off the request path entirely: enqueue a job and return 202 with a status URL.
2. 2Use worker threads for CPU-bound work that must stay in-process, with a bounded pool.
3. 3Stream instead of buffering — parse and process large payloads incrementally.
4. 4Use the async variants of every API. If a method name ends in Sync in a request handler, it is a bug.
5. 5Cap input size. A request body limit is a performance control as much as a security one.

Common misconceptions

• 'async makes it parallel' — no. An async function still runs its synchronous body on the main thread.
• 'Promise.all runs things in parallel' — it runs I/O concurrently; CPU work inside still serialises.
• 'setTimeout(fn, 0) defers to later' — it defers to the next timers phase, still on the same thread.
• 'Node is bad at CPU work' — it is fine at CPU work in a worker thread; it is bad at CPU work on the request thread.