Fix Error: ERR_STREAM_PREMATURE_CLOSE in Node.js

This error occurs when a readable or writable stream is closed or destroyed before it finished processing all data. Common causes include client disconnections during file downloads, premature stream.destroy() calls, or piping errors. Fix it by handling the 'error' event on all streams and using pipeline() for safe piping.

Reading the Stack Trace

Here's what each line means:

• at Writable.onclose (node:internal/streams/end-of-stream:142:30): The writable stream closed before the readable stream finished sending data, causing the premature close error.
• at emitCloseNT (node:internal/streams/destroy:132:10): Node's stream destruction logic emits the close event, triggering cleanup and error propagation.
• at downloadFile (src/handlers/fileHandler.js:31:12): Your file handler at line 31 uses pipe() without error handling, leaving the pipeline unprotected.

Common Causes

function downloadFile(req, res) {
  const stream = fs.createReadStream('/data/largefile.zip');
  stream.pipe(res); // No error handling if client disconnects
}

readStream.pipe(transformStream).pipe(writeStream);
// No error listener on any stream

stream.destroy(); // Called in a timeout or condition before data is fully processed

The Fix

Replace stream.pipe() with pipeline() which properly handles errors and cleanup across all streams in the chain. When the client disconnects, pipeline catches the premature close and cleans up the read stream.

const fs = require('fs');

function downloadFile(req, res) {
  const stream = fs.createReadStream('/data/largefile.zip');
  stream.pipe(res);
}

const fs = require('fs');
const { pipeline } = require('stream');

function downloadFile(req, res) {
  const stream = fs.createReadStream('/data/largefile.zip');

  res.setHeader('Content-Type', 'application/octet-stream');

  pipeline(stream, res, (err) => {
    if (err) {
      if (err.code === 'ERR_STREAM_PREMATURE_CLOSE') {
        console.warn('Client disconnected during download');
      } else {
        console.error('Stream pipeline error:', err);
      }
      stream.destroy();
    }
  });
}

Testing the Fix

const { Readable, Writable } = require('stream');
const { pipeline } = require('stream');

describe('Stream pipeline', () => {
  it('handles premature close gracefully', (done) => {
    const readable = new Readable({ read() { this.push('data'); } });
    const writable = new Writable({
      write(chunk, enc, cb) {
        writable.destroy(); // Simulate client disconnect
        cb();
      },
    });

    pipeline(readable, writable, (err) => {
      expect(err).toBeDefined();
      expect(err.code).toBe('ERR_STREAM_PREMATURE_CLOSE');
      done();
    });
  });

  it('completes successfully when no errors occur', (done) => {
    const readable = Readable.from(['hello', 'world']);
    const chunks = [];
    const writable = new Writable({
      write(chunk, enc, cb) { chunks.push(chunk.toString()); cb(); },
    });

    pipeline(readable, writable, (err) => {
      expect(err).toBeUndefined();
      expect(chunks).toEqual(['hello', 'world']);
      done();
    });
  });
});

Run your tests:

npm test

Pushing Through CI/CD

git checkout -b fix/nodejs-stream-premature-close,git add src/handlers/fileHandler.js src/handlers/__tests__/fileHandler.test.js,git commit -m "fix: use pipeline() for stream piping to handle premature close",git push origin fix/nodejs-stream-premature-close

Your CI config should look something like this:

name: CI
on:
  pull_request:
    branches: [main]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
      - run: npm ci
      - run: npm test -- --coverage
      - run: npm run lint

The Full Manual Process: 18 Steps

Here's every step you just went through to fix this one bug:

1. Notice the error alert or see it in your monitoring tool
2. Open the error dashboard and read the stack trace
3. Identify the file and line number from the stack trace
4. Open your IDE and navigate to the file
5. Read the surrounding code to understand context
6. Reproduce the error locally
7. Identify the root cause
8. Write the fix
9. Run the test suite locally
10. Fix any failing tests
11. Write new tests covering the edge case
12. Run the full test suite again
13. Create a new git branch
14. Commit and push your changes
15. Open a pull request
16. Wait for code review
17. Merge and deploy to production
18. Monitor production to confirm the error is resolved

Total time: 30-60 minutes. For one bug.

npm install bugstack-sdk

const { initBugStack } = require('bugstack-sdk')

initBugStack({ apiKey: process.env.BUGSTACK_API_KEY })

Deploying the Fix (Manual Path)

1. Replace all .pipe() calls with pipeline() across the codebase.
2. Add error handlers for each stream pipeline.
3. Run tests to verify graceful handling of premature closes.
4. Open a pull request and wait for CI.
5. Merge and monitor error logs for stream-related issues.

Frequently Asked Questions