Error propagation between gulp.src and gulp.dest: automatic pipeline termination vs plugin‑level handling

Short answer

No to all three regarding core Gulp behavior. In Gulp 4, gulp.src does not unpipe downstream when a plugin errors, gulp.dest does not re-emit upstream errors, and the framework does not provide a global 'terminate-on-error' mode. Error handling is left to user code and individual plugins to maintain compatibility with watch modes and incremental builds.

The mechanism of propagation

Gulp is built on Node.js streams. When a plugin in the middle of a pipeline emits an error, that event travels through the stream. However, Node.js streams do not automatically destroy the pipeline unless told to. If an error is unhandled, the Node process will crash; if it is handled, the stream may hang or continue in inconsistent states.

• Backpressure: gulp.src respects backpressure. If a downstream transform is slow or buffers data, gulp.src will pause reading. Memory usage spikes if a plugin buffers entire files instead of streaming chunks.
• gulp.dest behavior: gulp.dest is a writable stream. It emits errors only if the write to the disk fails (e.g., permissions issues). It does not wrap transform errors to signal its own failure.

How to implement explicit termination

To ensure a pipeline terminates on the first error, use the native stream.pipeline method or a utility like gulp-plumber. This ensures that all streams in the chain are properly destroyed when one fails.

const { src, dest } = require('gulp');
const { pipeline } = require('stream');
const through = require('through2');

function buildTask() {
  return pipeline(
    src('src/**/*.js'),
    through.obj(function(file, enc, cb) {
      if (file.path.includes('error')) {
        return cb(new Error('Simulated plugin failure'));
      }
      cb(null, file);
    }),
    dest('dist/'),
    (err) => {
      if (err) {
        console.error('Pipeline failed:', err);
        process.exit(1);
      }
    }
  );
}

Verification

To verify this, create a minimal pipeline with gulp.src, a transform that emits an error on a specific file, and gulp.dest. Observe if gulp.dest finishes processing or hangs. If the process continues to process subsequent files, the error is swallowed or the pipeline is not destroyed.