Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

Gulp crashes at start with "primordials is not defined"

ErrorReferenceError: primordials is not defined

Short answer

This error means an old copy of graceful-fs, pulled in by Gulp 3, is running on a Node.js version it cannot work with. Gulp 4 does not ship that old copy. Upgrade to a current gulp, move gulp-sass to the sass package, and find any other dependency that still drags Gulp 3 into your lockfile.

  • Applies to Node.js 22, Node.js 24, gulp 4, gulp-sass 5
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Find out which gulp and which graceful-fs your project really resolves. If gulp is 3.x or graceful-fs is 3.x, this page is your problem.

    npm ls gulp graceful-fs
  2. 2Match what you see, then jump to its fix

    1. 1npm ls shows gulp@3.x, and the stack trace starts in fs.js with the primordials lineThe project still runs Gulp 3Fix
    2. 2The gulpfile does require('gulp-sass') followed by a call to sass, or the build also fails in node-sassgulp-sass is on an old release or still uses node-sassFix
    3. 3package.json says gulp 4, but npm ls still shows gulp@3 under some other packageAnother dependency pulls Gulp 3 into the lockfileFix

What does the error look like?

  • ReferenceError: primordials is not defined
  • const { Math, Object, Reflect } = primordials;

Cause 1 of 3

The project still runs Gulp 3

1Check

The gulp maintainers traced this error to the natives module, which comes from a very outdated graceful-fs. Gulp 3 depends on that old chain; Gulp 4 does not. Check the version in package.json.

node --version
npx gulp --version
grep '"gulp"' package.json

2Fix

Install the gulp CLI globally and a current gulp locally, then rewrite the gulpfile for the gulp 4 task API: compose with gulp.series and gulp.parallel, and register tasks as plain functions.

npm rm --global gulp
npm install --global gulp-cli
npm install --save-dev gulp@latest

3Verify

The CLI starts and prints a local gulp version of 4 or higher.

gulp --version

Confirmed by github.com

Did this fix it?

Cause 2 of 3

gulp-sass is on an old release or still uses node-sass

1Check

Current gulp-sass wants Gulp 4 and a Sass compiler that you pass in yourself. Node Sass is deprecated, and Dart Sass is the recommended compiler.

npm ls gulp-sass sass node-sass

2Fix

Install sass next to gulp-sass and hand it to gulp-sass in the gulpfile. Remove node-sass.

npm uninstall node-sass
npm install --save-dev sass gulp-sass

// gulpfile.js
const sass = require('gulp-sass')(require('sass'));

3Verify

Run your styles task. It should compile without the ReferenceError.

npx gulp styles

Confirmed by github.com

Did this fix it?

Cause 3 of 3

Another dependency pulls Gulp 3 into the lockfile

1Check

A gulp maintainer says that on Gulp 4 the cause would be a different issue within your project, such as an incorrect lockfile. Ask npm why the old package is there.

npm explain gulp
npm explain graceful-fs

2Fix

Upgrade or replace the package that depends on Gulp 3. If it is dead, remove it. Then reinstall from a clean tree so the lockfile is rebuilt.

rm -rf node_modules package-lock.json
npm install

3Verify

No gulp 3 and no graceful-fs 3 remain in the tree.

npm ls gulp graceful-fs

Confirmed by github.com

Did this fix it?

How do I stop it coming back?

  • Keep gulp on a supported major version and read its release notes before a Node.js upgrade.
  • Commit the lockfile and run npm ls on the build server so an old transitive package shows up early.
  • Pin the Node.js version in .nvmrc or the engines field so CI and laptops agree.
  • Move new style builds to the sass package; Node Sass is deprecated.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Back end

ng serve says it cannot determine the project or target

Cannot determine project for command.

The Angular CLI looked through angular.json for a project that defines the target you asked for (serve, build, test) and found none, or found several and could not pick one.

3 causes, each with a fix

Back end

ng serve cannot find the dev-server builder package

Could not find the implementation for builder @angular/build:dev-server

The builder named in angular.json (for example @angular-devkit/build-angular:dev-server) is looked up as an npm package starting from the workspace root.

3 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.