# Fix "ReferenceError: primordials is not defined" by Upgrading gulp 3

Yes. An agent upgrades a gulp 3 build to current gulp so it runs on modern Node, rewrites the task wiring, compares the built files, and opens a pull request.

[Run this on Rush](https://cloud.getrush.ai/run/fix-primordials-is-not-defined/gulp/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

`ReferenceError: primordials is not defined` is what gulp 3 prints on Node 12 and every version since. The stack trace runs through `natives` and an old `graceful-fs` that gulp 3's `vinyl-fs` depends on, which tried to re-evaluate Node's internal `fs` source. No gulpfile change fixes it; the supported fix is a current gulp, and that means rewriting how tasks are composed. The agent begins by reproducing the error on the Node version in use. In a project like 720kb/radiobox.css, `package.json` has `gulp` at `^3.9.1` with `gulp-sass` at `^2.3.2` and `run-sequence`, no lockfile and no `scripts`. After `npm install`, `npx gulp build` on Node 22 fails at `fs.js:44` with exactly this error.

It then reads the build. The six-line `gulpfile.js` only calls `require('require-dir')('conf/tasks')`, and the nine files in that folder each register one task. `build.js` chains seven of them with `runSequence('clean', 'sass', 'autoprefixer', 'minify', 'banner', 'copy', 'finalize')`. `watcher.js` calls `gulp.watch(glob, ['build'])`. `sass.js` pipes through `gulp-sass` version 2, which wraps `node-sass`. The agent upgrades gulp and the plugins, passes a compiler to the new `gulp-sass` as `require('gulp-sass')(require('sass'))`, and replaces `run-sequence` with `gulp.series`, which is built in.

The direct translation fails, and the reason is specific to this layout. `gulp.task('build', gulp.series('clean', ...))` throws `Error: Task never defined: clean`, because `gulp.series` looks its task names up immediately and `require-dir` loads `build.js` before `clean.js`, in alphabetical order. gulp 3 with `run-sequence` resolved names when the task ran, so load order never mattered. The agent builds the series inside the task function so the lookup happens at run time, and applies the same change to the watcher, whose second argument must now be a function and no longer an array of names.

With that, `gulp build` runs all seven steps. The agent does not stop at a green run; it compares the output with the `dist` folder committed in the repository. The same 28 files are produced, and all fourteen minified stylesheets differ. One cause is harmless: the banner from `conf/paths.js` embeds today's date. The other is not cosmetic. The committed `radiobox.min.css` contains `@-webkit-keyframes` and `-webkit-transform`, and the new one has neither and is about a third of the size, because a current `gulp-autoprefixer` targets current browsers by default. The agent reports this with the byte counts and asks whether to add a `browserslist` entry that restores the old targets. It also notes the `@import` deprecation warnings Dart Sass now prints for the entry stylesheet.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "This project's gulp build fails on current Node with \"ReferenceError: primordials is not defined\". Fix it by upgrading from gulp 3 to the current gulp release, not by pinning an old Node or overriding graceful-fs. First install dependencies and run the build on the current Node LTS to reproduce the error, and record the exact message and the gulp version. Read the gulpfile and every task file it loads, and list each task, what it depends on, and how tasks are sequenced (run-sequence, dependency arrays, gulp.start). Upgrade gulp and each plugin to a release that supports it; replace node-sass based plugins with ones that take the sass package. Rewrite dependency arrays, run-sequence and gulp.start as gulp.series and gulp.parallel, make every task signal completion (return its stream or call the callback), and update gulp.watch calls to the new signature. If tasks are registered across several files, make sure names are resolved in an order that works, and explain what you did. If any task copies images, fonts or other binary files, pass encoding: false to gulp.src so they are not corrupted. Run every task that does not need a browser or a deploy target. Then compare the build output with the previous output, using committed build files if there are any: list files added, missing and changed, and for changed files explain each cause (timestamps, vendor prefixes, minifier differences, Sass compiler differences). Do not commit regenerated build output unless it was already tracked. Add a lockfile if the project has none and say so. Open a pull request.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

A pull request that changes `package.json`, adds a lockfile, and edits the task files that compose other tasks. For radiobox.css that is `build.js`, `watcher.js` and `sass.js`; the six tasks that only pipe a stream through a plugin are untouched. The description shows the error before and the task log after, with each of the seven steps starting and finishing in order.

The output comparison is the part that needs a human decision. It lists the changed files and attributes each difference: the date in the banner, and the vendor prefixes that a newer autoprefixer no longer adds. A reviewer who still supports old browsers answers with a browser list and the agent regenerates; one who does not accepts the smaller files. Either way the choice is made knowingly and written down in the pull request.

The reviewer also checks the dependencies that were removed. `run-sequence` goes because gulp replaces it, and `gulp-watch` goes because `watcher.js` imported it and then called `gulp.watch` anyway.

## Run it on every pull request labelled node-upgrade

This error usually appears the day someone raises the Node version in CI or in a Dockerfile, and the build of an older front-end package turns red. Add an automation to the repository's Project with a `github` trigger on `pull_request.labeled`, set its `labels` filter to `node-upgrade`, and save the prompt above. When a maintainer labels the pull request that raises Node, the run starts and the pull request event is placed after the saved prompt as event text. The agent opens its own pull request with the gulp upgrade, which you merge first.

The trigger fires only for labels applied by an owner, member or collaborator, and never for pull requests from forks. Use `branch_patterns` if only pull requests into your main branch should start it.

## Why run it on Rush?

The common answers to this error are workarounds: run Node 10 through a version manager, or force a newer `graceful-fs` with an override and leave gulp 3 in place. Both keep an unmaintained build alive. Doing the upgrade properly is a loop of install, run, read the error, fix, run again, and then a file-by-file comparison of the output, which is exactly the sort of work that gets postponed. The agent does the loop in its own sandbox, on the Node version you actually deploy with, and the commands and output are kept in the session transcript.

The comparison is why the result can be trusted. A build that exits zero says nothing about whether the CSS it wrote is the CSS you shipped last time. Here it is not: the new file is a third of the size, and nothing in the task log says so. A pull request that puts that difference in front of the reviewer, with its cause, is worth more than one that only turns the build green.

## Frequently asked questions

### Why does gulp 3 fail on newer Node versions?

gulp 3 depends on an old `graceful-fs` that patched Node's file system module by evaluating its internal source. Node 12 changed those internals to use an object called `primordials` that exists only inside Node itself, so the evaluated copy fails. gulp 4 and later do not use that technique.

### Can I fix it without upgrading gulp?

As a stopgap. An `overrides` entry in `package.json` (or `resolutions` with Yarn) that forces `graceful-fs` to a 4.x release lets gulp 3 start on some newer Node versions. It leaves you on a gulp that no longer receives fixes, with plugins that may fail for their own reasons, so treat it as a way to buy time.

### What replaces run-sequence and task dependency arrays?

`gulp.series` for tasks that must run in order and `gulp.parallel` for tasks that can run together. `gulp.task('name', ['dep'], fn)` becomes `gulp.task('name', gulp.series('dep', fn))`. Every task must return its stream or a promise, or call its callback, or gulp reports that it did not complete.

### Why do I get "Task never defined" after converting?

`gulp.series` and `gulp.parallel` resolve task names when they are called, not when the task runs. If the named task is registered later, in another file or further down the gulpfile, the lookup fails. Register tasks before composing them, or create the series inside a function so it is evaluated at run time.

### Will the upgraded build produce the same files?

The same file names, usually. Contents can change because the plugins were upgraded along with gulp: a newer autoprefixer adds fewer vendor prefixes, Dart Sass formats output differently from node-sass, and minifiers make different choices. The agent compares old and new output and explains each difference so you can decide which to keep.

## More gulp jobs

- [Replace Gulp With npm Scripts and a Plain Node Build Script](https://getrush.ai/run/migrate-gulp-to-npm-scripts/gulp/)
- [Fix "AssertionError: Task function must be specified" After Upgrading to gulp 4](https://getrush.ai/run/fix-gulp-task-function-must-be-specified/gulp/)
- [Fix "npm warn deprecated gulp-util: gulp-util is deprecated" in a Gulp Build](https://getrush.ai/run/fix-gulp-util-is-deprecated-warning/gulp/)

## More jobs like this: Upgrade dependencies weekly

- [Fix the punycode Deprecation Warning (DEP0040) in a Node.js Project](https://getrush.ai/run/fix-punycode-deprecation-warning/nodejs/)
- [Fix "AttributeError: module 'pytest' has no attribute 'config'" After Upgrading pytest](https://getrush.ai/run/fix-pytest-config-attribute-error/pytest/)
- [Fix "PytestRemovedIn10Warning: @pytest.yield_fixture is deprecated" Before pytest 10 Removes It](https://getrush.ai/run/fix-pytest-yield-fixture-is-deprecated-warning/pytest/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
