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.
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.
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.
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
List all Gulp tutorials.