How to fix “ReferenceError: primordials is not defined” in Node.js

If a project that ran fine last month suddenly dies with ReferenceError: primordials is not defined, you are almost certainly running an old Gulp 3 setup on a modern Node.js version. The error looks like Node.js is broken. It is not.

One old dependency patches the fs module in a way modern Node no longer allows.

I reproduced this exact failure on Node.js v26.7.0 with Gulp 3.9.1 while researching this article, and the fix below got the same project running without downgrading anything.

What causes the error

Primordials are internal JavaScript bindings that exist inside Node.js core source files. They are never available to your code or to packages. When a stack trace says primordials is not defined at fs.js:48, it means some package shipped its own patched copy of Node’s fs module, and that copy only works on the Node.js version it was written for.

The package doing the patching is almost always graceful-fs 3.x, which arrives as a dependency of Gulp 3. The full trace makes the chain visible:

Why Node.js 12+ breaks Gulp 3

Gulp 3 depends on vinyl-fs, which pulls in graceful-fs 3.0.x. That release monkey-patches Node’s built-in fs module using internals that were reorganized in Node.js 12 and have kept changing since. The moment any file in your project requires the patched module, Node throws ReferenceError: primordials is not defined before your own code runs a single line.

So the error has nothing to do with your gulpfile or your code. It is a version conflict between one unmaintained transitive dependency and every Node.js release from 2019 onward.

How to fix it

You have three options: pin a newer graceful-fs over the broken one, upgrade to Gulp 5, or downgrade Node.js. The first keeps your project unchanged today, the second is the durable fix, and the third trades security for compatibility. Start with the pin.

Pin graceful-fs with npm overrides

graceful-fs 4.x removed the patch that breaks modern Node, and its current release works everywhere from Node 12 up. npm overrides let you force that version even though Gulp 3 asks for 3.0.x. Add this to your package.json:

{
  "name": "legacy-gulp3",
  "version": "1.0.0",
  "private": true,
  "devDependencies": {
    "gulp": "^3.9.1"
  },
  "overrides": {
    "graceful-fs": "^4.2.11"
  }
}

Then reinstall from scratch so the override takes effect:

rm -rf node_modules package-lock.json
npm install

Run npx gulp again and the error is gone:

Yarn and pnpm equivalents

Yarn uses resolutions instead of overrides, and pnpm nests the key under pnpm. All three point at the same graceful-fs ^4.2.11 target:

// Yarn
{
  "resolutions": {
    "graceful-fs": "^4.2.11"
  }
}

// pnpm
{
  "pnpm": {
    "overrides": {
      "graceful-fs": "^4.2.11"
    }
  }
}

Reinstall after editing either file, then rerun your build task to confirm.

Upgrade to Gulp 5 when you can

The current Gulp release is 5.0.1, and it dropped the problematic dependency chain entirely. If your gulpfile is simple, migrating usually costs less than an afternoon: most tasks convert from task arrays to exports and from vinyl streams to the src/dest API. Check each plugin for a Gulp 4-compatible release while you migrate, since a few very old plugins will be the actual blockers.

Last resort: downgrade Node.js

Some teams pin Node.js 11 just to keep a legacy build alive. That puts you on a release with no security patches, so treat it as temporary.

If you must, use nvm and run the old toolchain in isolation. Our guide on how to downgrade Node to any version covers the steps. For broader context on runtime errors like this one, see our list of common NodeJS errors.

Wrapping up

ReferenceError: primordials is not defined means Gulp 3’s internal graceful-fs 3.x dependency cannot run on any Node.js version from 12 onward. Pin graceful-fs to ^4.2.11 with npm overrides to get moving today, verify with npx gulp, and schedule the migration to Gulp 5 so the fix does not need to live forever.