Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

A stream error crashes Node.js or leaves files open when you use pipe()

Errorthe process exits when a file or request stream fails

Short answer

An error on a stream is emitted as an error event. With no listener, Node.js throws and the process exits. pipe() also does not forward errors or close the destination, so files and sockets stay open. Use stream.pipeline from node:stream/promises, which fails on any stream and cleans up.

  • Applies to Node.js 22, Node.js 24
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Find the places that chain streams with pipe(). Each stream in such a chain needs its own error handling.

    grep -rn "\.pipe(" --include=*.js --include=*.mjs --include=*.ts . --exclude-dir=node_modules
  2. 2Match what you see, then jump to its fix

    1. 1The process dies with a stack trace the moment a read or write failsNo error listener on the streamFix
    2. 2A failed upload or read leaves the output file or socket open, and memory growspipe() does not pass errors on or close the destinationFix
    3. 3Listeners accumulate on streams you pass to finished()You wait for completion with finished() and leave listeners behindFix

What does the error look like?

  • the process exits when a file or request stream fails

Cause 1 of 3

No error listener on the stream

1Check

If an EventEmitter emits 'error' and has no listener for it, the error is thrown, a stack trace is printed and the process exits. Streams are EventEmitters.

node -e "const fs=require('fs'); fs.createReadStream('/missing')"

2Fix

Attach an error listener, or better, use pipeline which does it for every stream.

const fs = require('node:fs');
const src = fs.createReadStream(inputPath);
src.on('error', (err) => console.error('read failed', err));

3Verify

Run the same missing-file case again; the process now logs and survives.

node -e "require('fs').createReadStream('/missing').on('error', e => console.log('handled', e.code))"

Confirmed by nodejs.org

Did this fix it?

Cause 2 of 3

pipe() does not pass errors on or close the destination

1Check

If the Readable emits an error, the Writable destination is not closed automatically. Each stream in a pipe() chain must be closed by hand.

grep -rn "\.pipe(" src | wc -l

2Fix

Replace pipe() chains with pipeline from node:stream/promises. It rejects if any stream fails, so one try/catch covers the chain.

const { pipeline } = require('node:stream/promises');
const fs = require('node:fs');
const zlib = require('node:zlib');

async function compress(input, output) {
  try {
    await pipeline(
      fs.createReadStream(input),
      zlib.createGzip(),
      fs.createWriteStream(output),
    );
  } catch (err) {
    console.error('pipeline failed', err);
  }
}

3Verify

Call it with a missing input file; the catch block runs and the process stays up.

compress('/missing', '/tmp/out.gz');

Confirmed by nodejs.org

Did this fix it?

Cause 3 of 3

You wait for completion with finished() and leave listeners behind

1Check

stream.finished() leaves dangling listeners (error, end, finish, close) after its promise settles, unless cleanup is requested.

grep -rn "finished(" --include=*.js . --exclude-dir=node_modules

2Fix

Pass cleanup true.

const { finished } = require('node:stream/promises');
await finished(stream, { cleanup: true });

3Verify

Listener counts on the stream stay flat after it settles.

console.log(stream.listenerCount('error'));

Confirmed by nodejs.org

Did this fix it?

How do I stop it coming back?

  • Use pipeline instead of chains of pipe() whenever more than one stream is involved.
  • Give long-lived streams an error listener before data starts flowing.
  • Pass an AbortSignal to pipeline so you can stop a chain on timeout.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Back end

ng serve says it cannot determine the project or target

Cannot determine project for command.

The Angular CLI looked through angular.json for a project that defines the target you asked for (serve, build, test) and found none, or found several and could not pick one.

3 causes, each with a fix

Back end

ng serve cannot find the dev-server builder package

Could not find the implementation for builder @angular/build:dev-server

The builder named in angular.json (for example @angular-devkit/build-angular:dev-server) is looked up as an npm package starting from the workspace root.

3 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.