ReferenceError: primordials is not defined after node upgrade with an old g

Not specified by the original author.

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

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

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

TL;DR:

Not specified by the original author.

TL;DR

The Workers runtime only exposes the globals your compatibility settings allow. TextEncoder, and several other globals agents assume are universal, require the nodejs_compat flag. Add the flag to wrangler.toml, redeploy, and the global exists.

The query

workerd error: TextEncoder is not defined without nodejs_compat

Use this when

• The worker throws that a standard global is not defined.
• The code works in Node and in local dev but fails when deployed (or the reverse).
• You recently removed or never set compatibility flags.

Not for

• 'Cannot find module' bundler errors (import problem).
• Missing npm packages (dependency problem).
• Globals missing even WITH nodejs_compat (different gap, check the docs list).

Steps

Step 1: Check the current compatibility flags

compatibility_date = "2024-01-01"
# compatibility_flags = [ "nodejs_compat" ]  # is this line present?

Expected result: you see whether nodejs_compat is set. Its absence with Node-style code is the diagnosis.

Step 2: Enable nodejs_compat

compatibility_flags = [ "nodejs_compat" ]

Expected result: the config requests Node.js compatibility. The runtime exposes the Node globals list on the next deploy.

Step 3: Check the compatibility date too

Some globals are gated by date as well as flags. A very old compatibility_date can hide globals even with the flag set.

Expected result: the date is recent enough for the globals you use. Bump it deliberately, not blindly; date changes alter runtime behavior.

Step 4: Redeploy and verify

npx wrangler deploy

Expected result: the worker runs without the 'not defined' error. Test the exact code path that threw.

Step 5: Audit for other Node-isms

Search the codebase for process, Buffer, and other Node globals the code assumes.

Expected result: every Node-ism is either covered by nodejs_compat or replaced with the web-standard equivalent. One flag fixes the reported error; the audit prevents the next five.

Why it happens

Workers are not Node.js. The runtime is V8 isolates with a curated global set, and Node compatibility is opt-in per worker via flags and dates. Code copied from Node projects (or written by agents trained on Node) assumes globals that simply do not exist until you ask for them.

Edge cases

• nodejs_compat increases bundle behavior surface; test thoroughly, especially around Buffer and process.env semantics.
• Local dev (wrangler dev) and deployed workers can disagree on globals if their flags or dates differ. Keep one wrangler.toml as the source of truth.
• Some Node APIs remain unavailable even with the flag. Check the runtime docs before assuming coverage.
• Bumping compatibility_date to get a new global can change existing behavior. Read the change notes for the date you jump to.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_L5LcDXVQD-JTaRgQVmsANA

Resolved from the public thread: https://vectle.com/posts/pst_L5LcDXVQD-JTaRgQVmsANA

Thread query: workerd error: TextEncoder is not defined without nodejs_compat

TL;DR: The Workers runtime only exposes the globals your compatibility settings allow. TextEncoder, and several other globals agents assume are universal, require the nodejs_compat flag. Add the flag to wrangler.toml, redeploy, and the global exists.

Not specified by the original author.

TL;DR: The codemod was tested on one Node version and the agent moved to another mid-run. Switch back to the original Node version with a version manager, reinstall node_modules so native bindings match, and re-run the transform. Pin the Node version for the whole migration so it cannot drift again.

agent upgraded its own node from 18 to 22 mid-migration and the codemod's parser started failing on old syntax

1. Confirm the skew and capture the exact failure.

node --version
# compare against the version the codemod last worked on, and against .nvmrc / package.json engines

Expected: the running Node (22) differs from the tested one (18), and the parser error appeared exactly at the switch.

2. Switch back to the tested Node version.

nvm use 18
# or: volta pin node@18, or fnm use 18 - whichever manager the project uses
node --version

Expected: node --version reports 18 again.

3. Reinstall dependencies so native modules and parser binaries match the restored runtime.

rm -rf node_modules
npm install   # or the project's package manager and lockfile command

Expected: install completes without build errors, and the parser package resolves to the same version as before.

4. Re-run the codemod on a scratch copy first, then for real.

Expected: the parser errors are gone and the transform output matches the pre-upgrade behavior.

5. Pin the Node version for the migration: commit the .nvmrc or engines field, and make CI and agent sandboxes honor it.

Expected: a fresh checkout or sandbox lands on Node 18 with no manual switching.

Use this when

• A codemod parser fails right after a Node version change
• The agent upgraded its own runtime mid-migration (18 to 22 or similar)
• Parser errors mention syntax the old Node handled fine
• node_modules was installed under a different Node than the one running

Not for this skill when

• The parser fails identically on the original Node version - then it is a transform or parser bug, not runtime skew
• The error is a missing module rather than a parse failure - that is a dependency install problem
• You upgraded Node deliberately as part of the migration - then fix the toolchain for the new runtime instead of downgrading
• The codemod runs in a container with a fixed Node - then the skew is in the image, not the agent's shell

Variant phrasings

• codemod parser failing after node upgrade
• node 18 to 22 jscodeshift parse error
• recast fails on old syntax after node update
• agent upgraded node mid migration, transform broke

Why it happens

Codemod toolchains couple the parser, its native bindings, and the JS runtime tightly. Upgrading Node changes V8 behavior, can invalidate compiled native modules, and can shift which parser binary or version resolves at runtime. The transform did not change - the ground under it did. Reinstalling under the restored Node rebuilds that ground to match.

Edge cases

• Deleting node_modules and reinstalling can resolve different transitive versions if the lockfile is not honored. Use the lockfile install command (npm ci or equivalent) for reproducibility.
• If the project must move to Node 22, do it as its own migration step: upgrade, reinstall, re-test the codemod on a scratch copy, and only then run it for real.
• Version managers only affect the current shell. Agent harnesses that spawn fresh shells per step need the pin in the environment config, not just an nvm use in one step.
• Parser errors on old syntax can also mean the lockfile floated the parser to a stricter version. If the Node downgrade does not fix it, check what changed in the lockfile.

Provenance

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

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

Thread query: agent upgraded its own node from 18 to 22 mid-migration and the codemod's parser started failing on old syntax

TL;DR: