ReferenceError: primordials is not defined" after node upgrade with an old graceful-fs

TL;DR: graceful-fs version 3 reaches into Node's private internals, which were removed in Node 12 and later, so upgrading Node breaks every copy of graceful-fs@3 in the tree. Find which dependency drags it in with npm ls graceful-fs and upgrade that dependency to a version using graceful-fs@4. If the dependent is abandoned, pin graceful-fs to v4 with an override.

ReferenceError: primordials is not defined

1. Find the carrier: npm ls graceful-fs. Expected: the output shows the dependency chain, ending at graceful-fs@3 under some top-level package.

2. Identify the top-level package responsible for the graceful-fs@3 copy. Expected: you can name the package to upgrade (the classic carrier is gulp 3).

3. Upgrade that package to a release that depends on graceful-fs@4 (or run npm update graceful-fs if it is a direct dependency). Expected: npm ls graceful-fs now shows only v4 copies.

4. If the carrying package is abandoned and has no fixed release, add an npm override pinning graceful-fs to ^4. Expected: a fresh install resolves graceful-fs@4 everywhere the override applies.

5. Re-run the build or test that failed. Expected: no primordials error; the tool runs on the new Node version.

Use this when

• Node was just upgraded and the exact "primordials is not defined" error appears.
• The stack trace mentions graceful-fs or the natives module.
• npm ls graceful-fs shows a v3 copy anywhere in the tree.

Not for this skill when

• The "is not defined" error names something else entirely; that is a different bug.
• graceful-fs is already v4 everywhere; the problem lies elsewhere.
• The Node version is older than what the toolchain supports; upgrade Node instead.

Variant phrasings

• "ReferenceError primordials is not defined gulp"
• "graceful-fs primordials node upgrade"
• "primordials is not defined after node 14 upgrade"
• "natives module primordials error"

Why it happens

graceful-fs@3 monkey-patched Node's internal modules to work around old filesystem bugs, referencing private bindings through the natives module. Node 12 removed those internals, so any transitive graceful-fs@3 throws the moment it loads. The fix is always at the dependency that drags it in, because application code never requires graceful-fs directly.

Edge cases

• gulp 3 is the most common carrier and cannot run on modern Node at all; upgrading to gulp 4 is the real fix, not just the graceful-fs pin.
• Yarn uses a resolutions field and pnpm its own overrides syntax; the mechanism differs but the pin target is the same.
• After changing the tree, native modules may need a rebuild against the new Node version.
• Check for nested copies: one upgraded top-level package can still leave a v3 copy under a different parent.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst7yaj4astRbUYc9x3umoAA