Event-Loop Stall Incident

Q: How much JSON is too much on main thread?

Rule of thumb: >100KB sync parse on hot path deserves review; >1MB should not run on API tier main thread.

Q: How to reproduce locally?

autocannon on /health while posting 3MB JSON to heavy endpoint.

Q: Streaming JSON parsers?

stream-json for array items without loading full tree - good for imports.

Q: clinic flame vs doctor?

doctor highlights event-loop delay; flame shows CPU stacks - use both.

When one request runs synchronous CPU work - parsing a 5MB JSON body, JSON.stringify on huge objects, bcrypt.compare in a loop - the entire Node.js process stops serving other requests. Health checks fail; ALB marks pods unhealthy.

Recipe

Quick-reference recipe card - copy-paste ready.

// BAD: sync parse on hot path
app.post("/import", express.text({ limit: "10mb" }), (req, res) => {
  const rows = JSON.parse(req.body); // blocks event loop for large payloads
  res.json({ count: rows.length });
});
 
// BETTER: stream + worker or async chunking
import { Worker } from "node:worker_threads";
 
function parseInWorker(json: string): Promise<unknown> {
  return new Promise((resolve, reject) => {
    const w = new Worker(new URL("./parse-worker.ts", import.meta.url), {
      workerData: json,
    });
    w.on("message", resolve);
    w.on("error", reject);
    w.on("exit", (code) => code !== 0 && reject(new Error(`worker exit ${code}`)));
  });
}

clinic doctor --on-port 'autocannon -c 20 -d 30 localhost:3000/health' -- node dist/main.js

When to reach for this:

All endpoints slow when one heavy endpoint runs
Single-core CPU at 100% while event-loop lag metric spikes
/health times out during bulk import jobs on same process
After adding JSON.parse on webhook bodies without size limits

Working Example

import express from "express";
import { performance, monitorEventLoopDelay } from "node:perf_hooks";
 
const loopDelay = monitorEventLoopDelay({ resolution: 20 });
loopDelay.enable();
 
const app = express();
 
// Incident reproduction: 3MB JSON array sync parse
app.post("/webhooks/heavy", express.raw({ type: "application/json", limit: "5mb" }), (req, res) => {
  const start = performance.now();
  const payload = JSON.parse(req.body.toString("utf8"));
  const elapsed = performance.now() - start;
  res.json({ items: payload.length, parseMs: elapsed });
});
 
// Mitigation: reject oversized sync parse routes; offload to queue
app.post("/webhooks/queued", express.raw({ type: "application/json", limit: "256kb" }), (req, res) => {
  if (req.body.length > 256 * 1024) {
    return res.status(413).json({ error: { code: "PAYLOAD_TOO_LARGE" } });
  }
  const payload = JSON.parse(req.body.toString("utf8"));
  res.status(202).json({ accepted: true, items: payload.length });
});
 
app.get("/health", (_req, res) => {
  const p99 = loopDelay.percentile(99) / 1e6; // ms
  if (p99 > 100) return res.status(503).json({ ok: false, eventLoopLagP99Ms: p99 });
  res.json({ ok: true, eventLoopLagP99Ms: p99 });
});
 
app.listen(3000);

// parse-worker.ts
import { parentPort, workerData } from "node:worker_threads";
const data = JSON.parse(workerData as string);
parentPort?.postMessage({ length: Array.isArray(data) ? data.length : 0 });

What this demonstrates:

monitorEventLoopDelay exposes lag on /health for kube readiness
Size cap prevents accidental multi-MB sync parse on API tier
Worker thread moves parse off main event loop
clinic doctor correlates event-loop delay with CPU profile

Deep Dive

How It Works

Node runs JavaScript on one main thread per process (by default)
libuv thread pool handles some I/O; CPU in JS blocks timers and HTTP responses
Sync zlib, crypto, fs also stall - not only JSON
Cluster module or multiple pods spread load but one heavy request still stalls one core

Stall Signatures

Metric	Stall pattern
Event loop delay	p99 >> 50ms
CPU	One core 100%
Concurrent slow routes	All routes, not one DB
DB wait time	Normal

Mitigations

Workload	Mitigation
Large JSON parse	Worker, streaming parser, queue job
Image resize	Sharp in worker pool
Password verify	Bounded concurrency queue
Report generation	Background worker + S3 link

TypeScript Notes

// bcrypt in request path - limit concurrency
import { Semaphore } from "async-mutex"; // or tiny custom semaphore
const bcryptSlots = new Semaphore(4);

Gotchas

Bigger pods do not fix sync parse - More RAM, same blocked thread. Fix: Async boundary or worker.
Raising body limit without architecture - limit: '50mb' invites stalls. Fix: Upload to S3; process async.
Logging huge objects - JSON.stringify(big) in pino serializer stalls loop. Fix: Log ids only.
Regex catastrophic backtracking - Evil input hangs CPU. Fix: Safe regex, input length caps, re2 native.
Ignoring health during batch - Cron on API process runs sync job. Fix: Separate worker deployment.

Alternatives

Alternative	Use When	Don't Use When
Worker threads	CPU-bound JS chunks	Tiny parse <1ms
Child process	Isolate crash-prone native code	Need shared memory
Queue (BullMQ)	Any heavy job	Need synchronous response
Horizontal scale	I/O bound only	CPU bound per request

FAQs

How much JSON is too much on main thread?

Rule of thumb: >100KB sync parse on hot path deserves review; >1MB should not run on API tier main thread.

Does Fastify schema validation stall?

Large body validation still runs on main thread - cap body size and offload heavy transforms.

What is monitorEventLoopDelay threshold?

Alert p99 > 50-100ms sustained. Tune per SLO.

cluster.fork helps?

Spreads connections across cores; each worker still stalls independently on heavy request.

UV_THREADPOOL_SIZE for crypto?

Increases libuv pool for some crypto/fs - does not fix pure JS JSON.parse stall.

How to reproduce locally?

autocannon on /health while posting 3MB JSON to heavy endpoint.

NestJS interceptors?

Interceptor doing sync transform on large DTO - same issue; move to worker.

Streaming JSON parsers?

stream-json for array items without loading full tree - good for imports.

Production kill switch?

Feature flag disable import endpoint; scale workers only.

clinic flame vs doctor?

doctor highlights event-loop delay; flame shows CPU stacks - use both.

Debugging Basics - profiling tools
Memory Leak Hunt - different symptom (RSS growth)
Performance Basics - capacity planning
Worker Threads - offload CPU
Queues & Workers - async jobs

Node.js API Documentation - Complete reference for core modules and APIs.
NodeSource Blog & Resources - Enterprise Node.js performance and security content.
Node.js Best Practices (GitHub) - Curated production best practices.
Node.js Design Patterns, 4th Edition - Production-grade application patterns.
Distributed Systems with Node.js - Enterprise-ready distributed systems.

Stack versions: This page was written for Node.js 24.18.0 (Active LTS), npm 10+, TypeScript 5.6+, Express 5, Fastify 5, and NestJS 11.

Recipe

Quick-reference recipe card - copy-paste ready.

// BAD: sync parse on hot path
app.post("/import", express.text({ limit: "10mb" }), (req, res) => {
  const rows = JSON.parse(req.body); // blocks event loop for large payloads
  res.json({ count: rows.length });
});
 
// BETTER: stream + worker or async chunking
import { Worker } from "node:worker_threads";
 
function parseInWorker(json: string): Promise<unknown> {
  return new Promise((resolve, reject) => {
    const w = new Worker(new URL("./parse-worker.ts", import.meta.url), {
      workerData: json,
    });
    w.on("message", resolve);
    w.on("error", reject);
    w.on("exit", (code) => code !== 0 && reject(new Error(`worker exit ${code}`)));
  });
}

clinic doctor --on-port 'autocannon -c 20 -d 30 localhost:3000/health' -- node dist/main.js

When to reach for this:

All endpoints slow when one heavy endpoint runs
Single-core CPU at 100% while event-loop lag metric spikes
/health times out during bulk import jobs on same process
After adding JSON.parse on webhook bodies without size limits

Working Example

import express from "express";
import { performance, monitorEventLoopDelay } from "node:perf_hooks";
 
const loopDelay = monitorEventLoopDelay({ resolution: 20 });
loopDelay.enable();
 
const app = express();
 
// Incident reproduction: 3MB JSON array sync parse
app.post("/webhooks/heavy", express.raw({ type: "application/json", limit: "5mb" }), (req, res) => {
  const start = performance.now();
  const payload = JSON.parse(req.body.toString("utf8"));
  const elapsed = performance.now() - start;
  res.json({ items: payload.length, parseMs: elapsed });
});
 
// Mitigation: reject oversized sync parse routes; offload to queue
app.post("/webhooks/queued", express.raw({ type: "application/json", limit: "256kb" }), (req, res) => {
  if (req.body.length > 256 * 1024) {
    return res.status(413).json({ error: { code: "PAYLOAD_TOO_LARGE" } });
  }
  const payload = JSON.parse(req.body.toString("utf8"));
  res.status(202).json({ accepted: true, items: payload.length });
});
 
app.get("/health", (_req, res) => {
  const p99 = loopDelay.percentile(99) / 1e6; // ms
  if (p99 > 100) return res.status(503).json({ ok: false, eventLoopLagP99Ms: p99 });
  res.json({ ok: true, eventLoopLagP99Ms: p99 });
});
 
app.listen(3000);

// parse-worker.ts
import { parentPort, workerData } from "node:worker_threads";
const data = JSON.parse(workerData as string);
parentPort?.postMessage({ length: Array.isArray(data) ? data.length : 0 });

What this demonstrates:

monitorEventLoopDelay exposes lag on /health for kube readiness
Size cap prevents accidental multi-MB sync parse on API tier
Worker thread moves parse off main event loop
clinic doctor correlates event-loop delay with CPU profile

Deep Dive

How It Works

Node runs JavaScript on one main thread per process (by default)
libuv thread pool handles some I/O; CPU in JS blocks timers and HTTP responses
Sync zlib, crypto, fs also stall - not only JSON
Cluster module or multiple pods spread load but one heavy request still stalls one core

Stall Signatures

Metric	Stall pattern
Event loop delay	p99 >> 50ms
CPU	One core 100%
Concurrent slow routes	All routes, not one DB
DB wait time	Normal

Mitigations

Workload	Mitigation
Large JSON parse	Worker, streaming parser, queue job
Image resize	Sharp in worker pool
Password verify	Bounded concurrency queue
Report generation	Background worker + S3 link

TypeScript Notes

// bcrypt in request path - limit concurrency
import { Semaphore } from "async-mutex"; // or tiny custom semaphore
const bcryptSlots = new Semaphore(4);

Gotchas

Bigger pods do not fix sync parse - More RAM, same blocked thread. Fix: Async boundary or worker.
Raising body limit without architecture - limit: '50mb' invites stalls. Fix: Upload to S3; process async.
Logging huge objects - JSON.stringify(big) in pino serializer stalls loop. Fix: Log ids only.
Regex catastrophic backtracking - Evil input hangs CPU. Fix: Safe regex, input length caps, re2 native.
Ignoring health during batch - Cron on API process runs sync job. Fix: Separate worker deployment.

Alternatives

Alternative	Use When	Don't Use When
Worker threads	CPU-bound JS chunks	Tiny parse <1ms
Child process	Isolate crash-prone native code	Need shared memory
Queue (BullMQ)	Any heavy job	Need synchronous response
Horizontal scale	I/O bound only	CPU bound per request

FAQs

How much JSON is too much on main thread?

Rule of thumb: >100KB sync parse on hot path deserves review; >1MB should not run on API tier main thread.

Does Fastify schema validation stall?

Large body validation still runs on main thread - cap body size and offload heavy transforms.

What is monitorEventLoopDelay threshold?

Alert p99 > 50-100ms sustained. Tune per SLO.

cluster.fork helps?

Spreads connections across cores; each worker still stalls independently on heavy request.

UV_THREADPOOL_SIZE for crypto?

Increases libuv pool for some crypto/fs - does not fix pure JS JSON.parse stall.

How to reproduce locally?

autocannon on /health while posting 3MB JSON to heavy endpoint.

NestJS interceptors?

Interceptor doing sync transform on large DTO - same issue; move to worker.

Streaming JSON parsers?

stream-json for array items without loading full tree - good for imports.

Production kill switch?

Feature flag disable import endpoint; scale workers only.

clinic flame vs doctor?

doctor highlights event-loop delay; flame shows CPU stacks - use both.

Debugging Basics - profiling tools
Memory Leak Hunt - different symptom (RSS growth)
Performance Basics - capacity planning
Worker Threads - offload CPU
Queues & Workers - async jobs

Node.js API Documentation - Complete reference for core modules and APIs.
NodeSource Blog & Resources - Enterprise Node.js performance and security content.
Node.js Best Practices (GitHub) - Curated production best practices.
Node.js Design Patterns, 4th Edition - Production-grade application patterns.
Distributed Systems with Node.js - Enterprise-ready distributed systems.

Stack versions: This page was written for Node.js 24.18.0 (Active LTS), npm 10+, TypeScript 5.6+, Express 5, Fastify 5, and NestJS 11.

Event-Loop Stall Incident

Search Documentation

Event-Loop Stall Incident