How to handle stream errors?

This article is based on Node v16.14.0.

Streams are a built-in feature in Node.js and represent asynchronous flow of data. Streams are also a way to handle reading and/or writing files. A Node.js stream can help process large files, larger than the free memory of your computer, since it processes the data in small chunks.

Streams in Node.js

💰 The Pragmatic Programmer: journey to mastery. 💰 One of the best books in software development, sold over 200,000 times.

This is the third article of a series about streams in Node.js. It explains how to handle errors in streams.

Streams in Node.js

• What is a Stream in Node.js?
• Connect streams with the pipe method
• Handle stream errors (this article)
• Connect streams with the pipeline method
• How to use streams to ETL data
• How to stream to an HTTP response

Handling stream errors

Building robust Node.js applications requires dealing with errors in proper way. Have a look at the article series about Node.js errors for a refresher on errors - Errors in Node.js.

The most important event emitted by a stream is the error event. If this error event is not handled, it can crash your application. Hence, errors have to be handled when working with streams.

Error event handler

To handle error events attach an event handler directly on the stream.

Let's create a PassThrough stream and add event handlers.

Create a file.

touch streams-error-emit.js

Add code.

const { PassThrough } = require('stream');

const passThrough = new PassThrough();

passThrough.on('error', err => {
  console.error('passThrough encountered an error:', err);
});
process.stdin.on('error', err => {
  console.error('stdin encountered an error:', err);
});
process.stdout.on('error', err => {
  console.error('stdout encountered an error:', err);
});

process.stdin.pipe(passThrough).pipe(process.stdout);

passThrough.emit('error', new Error('Somewthing went wrong!'));

When you run the code with node stream-error-emit.js from the CLI the error will be first emitted from PassThrough, and then handled by it with throwing the error message passThrough encountered an error: Error: Somewthing went wrong!. Now try to remove the error handling for the PassThrough stream, just for fun. The example will crash with unhandled exception, exiting the program early and with a status code of 1.

Handling errors this way works and prevents your application from crashing. However, it can be unmanageable to attache these event handlers for every stream when working with the pipe method.

Handling errors with the pipeline method is much cleaner and manageable. The callback is called when the pipeline is fully done and can handle errors.

pipeline(
  // source stream,
  // transform or other streams,
  // destination stream,
  (err) => {
      if (err) {
        console.error('Pipeline failed.', err);
      } else {
        console.log('Pipeline succeeded.');
      }
    }
);

finished()

The finished() function gets triggered when a stream is no longer readable, writable or has experienced an error, or a premature close event. Handling errors with finished() is another option and was added in Node.js version 10. It takes a stream with options as first, and a callback as second argument - stream.finished(stream[, options], callback)-

const { finished } = require('stream');

const rs = fs.createReadStream('archive.tar');

finished(rs, err => {
  if (err) {
    console.error('Stream failed.', err);
  } else {
    console.log('Stream is done reading.');
  }
});

The finished function is especially useful in error handling scenarios, where a stream is destroyed prematurely (like an aborted HTTP request), and will not emit end or finish.

The finished API also provides a promise version:

const { finished } = require('stream/promises');

const rs = fs.createReadStream('archive.tar');

async function run() {
  await finished(rs);
  console.log('Stream is done reading.');
}

run().catch(console.error);
rs.resume(); // Drain the stream.

TL;DR

• Unhandled stream errors crash the application.
• One option to handle stream errors is to attach an event handler and listen to error events.
• Another option to handle errors is the finished function. It is especially useful in error handling scenarios, where end or finished are not emitted.
• The pipeline method provides an easier way to handle error events.

Thanks for reading and if you have any questions, use the comment function or send me a message @mariokandut.

If you want to know more about Node, have a look at these Node Tutorials.

References (and Big thanks):

HeyNode, Node.js - Streams, MDN - Streams