When clients upload 50 MB JSON bodies to one route, a Node.js API's p99 latency jumps on every endpoint; how do you confirm the cause and fix it?
answer
- receiving is cheap, the end is not
- one parse of the whole string
- delay spikes aligned with uploads
- raw bytes in, small result out
basics
~20 sThe route ends in one JSON.parse of the whole body on the main thread, freezing every other request. Confirm with loop-delay spikes aligned with uploads and a CPU profile; fix with a body cap, NDJSON parsed per line, or a worker thread.
solid answer
~40 sReceiving the body is asynchronous, but the JSON body parser collects it and calls `JSON.parse` once on the main thread; for a 50 MB string that holds the loop for a long, size-proportional stretch, so every endpoint's requests wait. I would confirm it with `monitorEventLoopDelay()` max and p99 spiking when uploads land, `eventLoopUtilization()` rising while dependencies stay flat, and a `node --cpu-prof` profile showing time in `JSON.parse`. Fixes: cap the body (check `Content-Length` and count streamed bytes); switch to NDJSON and parse line by line from the request stream; or move the parse and the processing into a `worker_threads.Worker` and return only a small result, because posting the parsed object back makes the main thread deserialize a structured clone of it. Raising `UV_THREADPOOL_SIZE` does nothing, since the parse never touches the threadpool.
code
javascript · 14 linesimport { Worker, isMainThread, parentPort, workerData } from 'node:worker_threads';
if (isMainThread) {
const rows = Array.from({ length: 200_000 }, (_, i) => ({ id: i, qty: i % 7 }));
const body = Buffer.from(JSON.stringify(rows));
const worker = new Worker(new URL(import.meta.url), { workerData: body });
worker.once('message', (summary) => console.log(summary));
worker.once('error', (err) => console.error('worker failed:', err));
} else {
const rows = JSON.parse(Buffer.from(workerData).toString('utf8'));
const totalQty = rows.reduce((sum, row) => sum + row.qty, 0);
parentPort.postMessage({ count: rows.length, totalQty });
}go deeper
Recall that JSON.parse is synchronous and runs on the main thread, however the bytes arrived, so a huge body stalls every request in the process.
Explain why receiving chunks is cheap while the single parse at the end is not, and why the threadpool plays no part in it.
Walk through proving it with loop delay, utilization and a CPU profile, then choose between a body cap, NDJSON and a worker, including the structured-clone cost of returning data.
Weigh changing the API contract to streaming records against isolating heavy imports in a separate service, and decide which limits every endpoint must enforce.
## Where the time goes Receiving a 50 MB upload is cheap for the event loop: the socket delivers the body in chunks, and each `'data'` callback only copies bytes. The expensive step comes at the end. A typical JSON body parser, including `json()` from `node:stream/consumers`, **collects the whole body, converts it to one string and calls `JSON.parse` once**. That call runs on the main thread inside V8, its cost grows with the size of the input, and it cannot be interrupted or split. The official Node.js guide on not blocking the event loop measured more than a second to parse a 50 MB string on its test machine. For that whole stretch Node runs no other callback. Requests to every other endpoint wait, so the p99 of the **whole API** rises, not just the upload route. That pattern (latency rising across unrelated endpoints, aligned with one kind of request) is the signature of a blocked loop rather than a slow dependency. Memory follows the same shape. The raw buffer, the decoded string and the parsed object graph all exist at the same moment, so one 50 MB upload can briefly need several times that much heap, and collecting it afterwards adds garbage-collection work of its own. ## Confirming it before changing code 1. **Loop delay.** Export `monitorEventLoopDelay()` p99 and `max` per instance. Spikes roughly as long as the parse, at the moments uploads land, point at the main thread. 2. **Utilization.** `performance.eventLoopUtilization()` jumps during the same windows while the dependency latency graphs stay flat. 3. **Correlation.** Line the spikes up with request logs: route, `Content-Length`, duration. 4. **Profile.** Reproduce in staging with `node --cpu-prof` (or the inspector's profiler via `--inspect`) while sending one large upload and a steady stream of small requests; the profile shows the time inside `JSON.parse` and the string conversion before it. ## The fix options | Option | What leaves the main thread | Cost | |---|---|---| | Cap the body size | nothing; the bound limits the worst case | clients needing big payloads must change | | NDJSON, parsed per line | nothing; each record is a small parse | contract change, streaming code | | Parse in a worker thread | the parse and the processing | memory per worker, copying input | | Separate service or job | everything | another deployable, async result | - **Cap first.** `node:http` passes the body to you as a stream and has no body-size limit of its own, so check `Content-Length` and count bytes as they stream, rejecting with 413 past the limit. Whatever else you choose, this bounds the worst case. - **Change the shape.** If the payload is a list of records, accept newline-delimited JSON and read it with `readline.createInterface({ input: req, crlfDelay: Infinity })` and `for await (const line of rl)`. Each line is a small `JSON.parse`, other requests interleave between chunks, and memory stays bounded. - **Offload.** Move the parse **and the work that needs the parsed data** into a `worker_threads.Worker`, and send back only a small result. - **Move it out.** For rare, heavy imports, accept the file into object storage, return 202, and process it in a separate worker service so it scales and fails independently. ## The worker-thread trap Threads in Node do not share JavaScript objects. `postMessage` and `workerData` copy values with the **structured clone algorithm**, and the receiving thread deserializes the copy. Posting a 50 MB parsed object graph back to the main thread makes the main thread deserialize it, which brings back a cost of the same order as the parse you moved. Copying the raw `Buffer` into the worker is far cheaper than a parse, and an `ArrayBuffer` can be moved instead of copied with a `transferList`. The rule: **raw bytes in, small result out**. Starting one worker per request also costs startup time and a separate heap, so a service reuses workers from a pool; building that pool is covered with worker threads. ## What does not help - **Raising `UV_THREADPOOL_SIZE`.** `JSON.parse` is JavaScript on the main thread; the libuv threadpool never sees it. - **Wrapping the parse in a promise.** The executor and `.then` callbacks run on the main thread just the same. - **Longer server timeouts.** They hide the symptom; the parse still freezes every other request. - **More `cluster` workers.** Other processes absorb other connections, but every request routed to the process doing the parse still stalls.
- Why not post the parsed object back from the worker to the main thread?`postMessage` copies values with the structured clone algorithm, and the receiving thread deserializes the copy. A 50 MB object graph arriving on the main thread costs the same order of time as the parse you moved off it. Keep the work that needs the data inside the worker and return a small result.
- How does accepting NDJSON change the blocking picture?Each line is a separate small `JSON.parse`. Reading the request with `readline.createInterface({ input: req, crlfDelay: Infinity })` and `for await (const line of rl)` parses records as chunks arrive, so other requests run between chunks and memory stays bounded instead of holding the whole body and its parsed copy.
- Would raising UV_THREADPOOL_SIZE help with the parse?No. `JSON.parse` is JavaScript running on the main thread; the libuv threadpool only serves native tasks such as fs, `dns.lookup`, async crypto and zlib. A bigger pool costs memory and changes nothing about the stall.
- Streaming the upload means the JSON parse is non-blocking too.
- JSON.parse runs on the libuv threadpool because the body came from a socket.
- Raising UV_THREADPOOL_SIZE will speed up large JSON parsing.
- Parsing in a worker and posting the whole object back removes the main-thread cost.
- Adding cluster workers makes the stalled process's own requests fast again.