If you’re working with a Node.js project that uses Gulp for task automation, you might suddenly hit a build wall after installing dependencies or switching environments. Everything seems fine until you try to run gulp, and then it breaks.

You might encounter the error “ReferenceError: primordials is not defined.” Don’t worry. This guide walks you through what causes this error, why it happens with specific versions of Node and Gulp, and how to resolve it without overhauling your entire stack.

What Causes the “ReferenceError: primordials is not defined” Error?

This error typically occurs when using Gulp 3.x with a newer version of Node.js, especially Node 14 and above. Gulp 3 relies on an outdated version of the graceful-fs module, which in turn depends on a Node.js internal object called primordials.

Since Node v12, primordials have been moved out of the global scope. Any package trying to access it directly (like older versions of graceful-fs) throws a ReferenceError. This usually affects projects that:

• Haven’t updated Gulp from v3 to v4
• Use older dependencies with indirect references to graceful-fs
• Install modules without resolving peer version conflicts

Ready to jump into the solutions?

Fix 1: Downgrade Node.js (Quickest Way)

If you’re using Gulp 3.x and need to get the project running quickly, the most straightforward fix is to downgrade Node.js to v12, which still exposes primordials globally.

Use Node Version Manager (NVM)

NVM is recommended as it lets you install and switch between multiple Node.js versions without affecting your system-wide installation. The best is that it is compatible with command-line interface (such as PowerShell, Command Prompt, or Git Bash) on Windows, or a POSIX-compliant shell like sh or bash on Linux/macOS

nvm install 12
nvm use 12

To avoid residual issues from previous installs, clean your project and reinstall everything

macOS/Linux:

rm -rf node_modules package-lock.json
npm install
gulp

Windows:

rd /s /q node_modules
del package-lock.json
npm install
gulp

Note: macOS users can also downgrade using Homebrew, but this replaces Node globally, making itn’t ideal for most dev workflows.

brew uninstall node
brew install node@12
brew link node@12 --force

Fix 2: Pin graceful-fs Version Using npm-shrinkwrap.json (Temp Fix)

The primordials error typically arises from an outdated graceful-fs version pulled in by Gulp 3.x. By forcing the version to 4.2.2, which avoids references to primordials, you can bypass the issue without changing your Node.js version.

Here are the steps on how to do it: 

1. Start by deleting node_modules and package-lock.json:

rm -rf node_modules package-lock.json

2. Next, create a file called npm-shrinkwrap.json in your project root:

{
  "dependencies": {
    "graceful-fs": {
      "version": "4.2.2"
    }
  }
}

3. Once done, install your dependencies again using the command: npm install, and then run Gulp using gulp.

Note: npm-shrinkwrap.json takes precedence over package-lock.json and locks transitive dependencies more strictly.

Fix 3: Upgrade Gulp to v4

Downgrading Node might temporarily fix the issue, but it isn’t permanent. The better fix is to upgrade your project to use Gulp 4, which is compatible with modern Node.js versions and no longer depends on deprecated internals like primordials.

To upgrade, use the command: npm install gulp@4.0.2 --save-dev, and if you face issues with version conflicts, use: npm install gulp@4.0.2 --force

After upgrading, Gulp tasks need to be updated to follow Gulp 4’s syntax using series() and parallel() from the gulp module. For example:

const { series } = require('gulp');
gulp.task('build', series('clean', 'scripts'));

Wrapping Up

The ReferenceError: primordials is not defined error usually signals an incompatibility between your Node.js version and Gulp setup. While downgrading Node works, upgrading to Gulp 4 is the long-term fix and often the cleaner one. Switching your tasks to use gulp.series() and running Gulp via npx also helps avoid global version conflicts.

As a best practice, always check your package.json to confirm that Gulp is set to ^4.0.2, and prefer local CLI usage over global installs. Some edge cases, like projects depending on native modules, may break on Node 22+.

In those cases, sticking to Node 20 or using npm-shrinkwrap.json to pin dependencies like graceful-fs@4.2.2 can help keep things stable.