Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท Concepts and Pitfalls

Backpressure in Node.js streams

Why Node.js streams need flow control, how write() returning false and the drain event work, and how pipeline() and async iteration handle it for you.

Backpressure is the way a slow consumer tells a fast producer to wait. Without it, a program that reads a huge file quickly and writes it to a slow network connection would pile the whole file into memory, because the writer cannot keep up with the reader.

In Node.js streams, backpressure is a small protocol built on two signals: the return value of writable.write() and the 'drain' event. Each stream has a buffer limit, the highWaterMark. When the buffered data reaches it, write() returns false: "stop sending". When the buffer has emptied, the stream emits 'drain': "you may continue".

NODE
if (!writable.write(chunk)) {
  await once(writable, 'drain');
}

Try it

Node.js write() returns false, then drain

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Node.js Respecting backpressure in a producer loop

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

How the protocol works

  1. A writable keeps incoming data in an internal queue and passes chunks to its _write() implementation one at a time.
  2. write() returns true while the queued size is below highWaterMark and false once it reaches or exceeds it. The data is still accepted; the false is advice, not a refusal.
  3. When the queue empties after a false, 'drain' fires exactly once.
  4. A readable-to-writable pipe() implements this loop for you: it pauses the readable on false and resumes it on 'drain'.

Because the stream always accepts the data, a producer that ignores false still works, but its memory use grows with every unread chunk. The second example shows the careless loop buffering all 2000 bytes at once, while the careful one stays within a few chunks.

Usage notes

  • Prefer stream.pipeline() over manual write() loops: it handles backpressure, forwards errors and destroys every stream on failure. See stream.pipeline().
  • Async iteration respects it too. for await (const chunk of readable) pulls data only as fast as your loop body finishes.
  • highWaterMark is a threshold, not a hard cap. For byte streams it counts bytes; in object mode it counts objects. See highWaterMark.
  • Readable streams have their own side: push() returns false when the internal buffer is full and _read() is called again when there is room.
  • Do not mix data listeners with pipe() on the same stream in ways that bypass pausing.
  • A missing 'drain' wait is a classic leak. Servers that copy a large upload to a slow disk or a slow client can run out of memory when each write ignores the result.
  • Check writableNeedDrain if you need to know whether a drain is pending without tracking the last return value.