ZetCode

Gulp error handling

last modified November 15, 2026

In this article we look at errors in Gulp 5 tasks. A failing plugin inside a pipe chain can go unnoticed, with a green build and stale files. We see why it happens, make the errors visible with pipeline, compare it with gulp-plumber and with an error handler, and keep watch running while a file contains an error.

Errors in streams

A Gulp task fails when it throws, when its promise is rejected, or when it calls done with an error. That is simple for ordinary functions, as the Gulp series and parallel tutorial shows. Streams are different. A stream reports a failure by emitting an error event, and pipe does not forward the event from one stream to the next. Gulp only watches the stream that the task returns, which is the last one of the chain, so an error in an earlier plugin is invisible to it.

Installing the project

We create a project and install Gulp, gulp-terser to minify the scripts, and gulp-plumber.

$ mkdir gulp-errors
$ cd gulp-errors
$ npm init -y
$ npm i -D gulp gulp-terser gulp-plumber
$ mkdir src

The example project

The project has two source files. The first one is valid.

src/app.js
const sum = (a, b) => { return a + b; }; console.log(sum(2, 3));

The second file has a syntax error: the closing parenthesis of the parameter list is missing.

src/broken.js
const broken = (a, b => { return a + b; };

The gulpfile defines all the tasks of this article. The failing function creates a Node.js Transform stream that fails for every file; it is the simplest possible failing plugin.

gulpfile.mjs
import { src, dest, watch, series } from 'gulp';
import { pipeline } from 'node:stream/promises';
import { Transform } from 'node:stream';
import terser from 'gulp-terser';
import plumber from 'gulp-plumber';

function failing() {

    return new Transform({
        objectMode: true,
        transform(file, encoding, callback) {
            callback(new Error(`cannot process ${file.relative}`));
        }
    });
}

export function swallowed() {

    return src('src/app.js')
        .pipe(failing())
        .pipe(dest('dist'));
}

export function piped() {

    return src('src/*.js')
        .pipe(terser())
        .pipe(dest('dist'));
}

export function withPipeline() {

    return pipeline(
        src('src/*.js'),
        terser(),
        dest('dist')
    );
}

export function withPlumber() {

    return src('src/*.js')
        .pipe(plumber())
        .pipe(terser())
        .pipe(dest('dist'));
}

export function withHandler(done) {

    src('src/*.js')
        .pipe(terser())
        .on('error', done)
        .pipe(dest('dist'))
        .on('end', done);
}

function build() {

    return pipeline(
        src('src/app.js'),
        terser(),
        dest('dist')
    );
}

function watchBuild() {

    watch('src/app.js', build);
}

export const dev = series(build, watchBuild);

export function failingPipeline() {

    return pipeline(
        src('src/app.js'),
        failing(),
        dest('dist')
    );
}

We look at the tasks one by one in the following sections.

A failing plugin in a pipe chain

The swallowed task pipes a file through the failing transform into dest. The transform reports an error, but nothing connects it to Gulp. The task neither finishes nor fails: when the process runs out of work, Gulp complains that the task did not complete and exits with status 1. The message sends us to the wrong place, because the real error is never printed.

$ npx gulp swallowed
[12:46:34] Using gulpfile ~/Documents/prog/js/gulp-errors/gulpfile.mjs
[12:46:34] Starting 'swallowed'...
[12:46:34] The following tasks did not complete: swallowed
Did you forget to signal async completion?
$ echo $?
1

A syntax error in gulp-terser

The piped task minifies both files. The plugin fails on broken.js and emits an error, but the task reports success and the exit status is 0. The valid file is written, the broken one is missing, and nothing says so. In a deployment script this means that incomplete or stale files go to production without a warning.

$ npx gulp piped
[12:46:34] Using gulpfile ~/Documents/prog/js/gulp-errors/gulpfile.mjs
[12:46:34] Starting 'piped'...
[12:46:34] Finished 'piped' after 40 ms
$ echo $?
0
$ ls dist
app.js

The pipeline function

The pipeline function from node:stream/promises connects the streams and listens for errors on every one of them. It returns a promise that is rejected with the first error, and Gulp accepts the promise as the result of the task.

return pipeline(
    src('src/*.js'),
    terser(),
    dest('dist')
);

Now the task fails and Gulp prints the message of Terser, with the position of the error in the file, and the exit status is 1. The files that were processed before the failure are written; pipeline does not undo them. The same applies to the failingPipeline task, whose error is a plain exception with a stack trace.

$ npx gulp withPipeline
[12:46:35] Using gulpfile ~/Documents/prog/js/gulp-errors/gulpfile.mjs
[12:46:35] Starting 'withPipeline'...
[12:46:35] 'withPipeline' errored after 33 ms
[12:46:35] SyntaxError in plugin "terser"
Message:
    Unexpected token punc «;», expected punc «,»
Details:
    filename: 0
    line: 1
    col: 41
    pos: 41

$ echo $?
1
$ npx gulp failingPipeline 2>&1 | head -4
[12:46:35] Using gulpfile ~/Documents/prog/js/gulp-errors/gulpfile.mjs
[12:46:35] Starting 'failingPipeline'...
[12:46:35] 'failingPipeline' errored after 13 ms
[12:46:35] Error: cannot process app.js

The gulp-plumber plugin

The gulp-plumber plugin is an older way to deal with the problem. Put at the start of the chain, it patches the streams that follow so that their errors are reported instead of being lost. The build continues without the file that failed.

return src('src/*.js')
    .pipe(plumber())
    .pipe(terser())
    .pipe(dest('dist'));

The error is printed with the heading "Plumber found unhandled error", and the task finishes successfully with exit status 0. This is what we want in a development watcher, where one typo should not stop the process. It is not what we want in a build for deployment, because the failure does not change the exit status. We can handle this with pipeline in builds and with plumber only in tasks used while developing.

$ npx gulp withPlumber
[12:46:36] Using gulpfile ~/Documents/prog/js/gulp-errors/gulpfile.mjs
[12:46:36] Starting 'withPlumber'...
[12:46:36] Plumber found unhandled error:
 SyntaxError in plugin "terser"
Message:
    Unexpected token punc «;», expected punc «,»
Details:
    filename: 0
    line: 1
    col: 41
    pos: 41

[12:46:36] Finished 'withPlumber' after 34 ms
$ echo $?
0
$ ls dist
app.js

An error handler

A third approach needs no extra plugin. A handler attached to the stream that may fail passes the error to the done callback, which fails the task. The end event of the last stream calls done without an error on success.

src('src/*.js')
    .pipe(terser())
    .on('error', done)
    .pipe(dest('dist'))
    .on('end', done);

The result is the same as with pipeline: the error is printed and the exit status is 1. The disadvantage is that we must attach a handler to every stream in the chain that can fail, and we have to remember to do it. pipeline does that for all the streams at once.

$ npx gulp withHandler
[12:46:36] Using gulpfile ~/Documents/prog/js/gulp-errors/gulpfile.mjs
[12:46:36] Starting 'withHandler'...
[12:46:36] 'withHandler' errored after 29 ms
[12:46:36] SyntaxError in plugin "terser"
Message:
    Unexpected token punc «;», expected punc «,»
Details:
    filename: 0
    line: 1
    col: 41
    pos: 41

$ echo $?
1

Keeping watch alive

While we develop, a typo is not a reason to stop the watcher. A failed task run by watch does not end the process: Gulp reports the error and the watcher keeps waiting for the next change. The condition is that the task really fails, which is why we use pipeline; the quiet chain would report success.

function build() {

    return pipeline(
        src('src/app.js'),
        terser(),
        dest('dist')
    );
}

export const dev = series(build, watchBuild);

In the experiment we break app.js and fix it a second later. The first build fails and prints the error, the second one succeeds, and the minified file in dist has the corrected content. The watcher survived the failure.

$ npx gulp dev
[12:46:36] Using gulpfile ~/Documents/prog/js/gulp-errors/gulpfile.mjs
[12:46:36] Starting 'dev'...
[12:46:36] Starting 'build'...
[12:46:36] Finished 'build' after 29 ms
[12:46:36] Starting 'watchBuild'...
[12:46:39] Starting 'build'...
[12:46:39] 'build' errored after 15 ms
[12:46:39] SyntaxError in plugin "terser"
Message:
    Unexpected token punc «;», expected punc «,»
Details:
    filename: 0
    line: 1
    col: 26
    pos: 26

[12:46:40] Starting 'build'...
[12:46:40] Finished 'build' after 10 ms
$ cat dist/app.js
const sum=(o,s)=>o+s;console.log(sum(4,5));

Source

Node.js stream.pipeline, Gulp async completion, gulp-plumber on npm

In this article we have handled errors in Gulp 5 tasks: we saw how pipe hides failures, made them visible with pipeline, compared gulp-plumber and error handlers, and kept watch running after a failed build. See also the Gulp Terser and Gulp watch tutorials.

Author

I am Jan Bodnar, a programmer and technical writer. I have been writing programming tutorials at ZetCode since 2007 and have published eight e-books. See about the author.

List all Gulp tutorials.