workerd error: TextEncoder is not defined without nodejs_compat

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: # Node.js compatibility on Workers, without the guessing Workers run on workerd (V8 isolates), not Node.js. Many npm packages import Node builtins ( node:fs

Node.js compatibility on Workers, without the guessing

Workers run on workerd (V8 isolates), not Node.js. Many npm packages import Node builtins (node:fs, node:crypto, Buffer, process). Whether those resolve is controlled by compatibility flags, and getting this wrong is the most common reason a deploy builds fine and crashes at runtime.

The date rule (current as of the docs, updated Aug 2026)

• compatibility_date of 2026-08-04 or later: nodejs_compat and nodejs_compat_v2 are enabled by default. Built-in Node.js APIs and polyfills work with no extra config. Do not add the flags to new configs.
• 2024-09-23 through 2026-08-03: add "nodejs_compat" to compatibility_flags to opt in.
• Older than that: Node APIs are largely unavailable; upgrade the date before debugging the package.

{
  "compatibility_date": "2026-08-03",
  "compatibility_flags": ["nodejs_compat"]
}

What the flags actually give you

Two forms: real built-in implementations of Node APIs in the runtime, and polyfill shims Wrangler adds at build time. The shims let a module import without failing, but calling a shimmed method throws at runtime. So "it bundled" is not proof "it runs". Test the actual code path.

Turning it off completely

For a date of 2026-08-04 or later, add both no_nodejs_compat and no_nodejs_compat_v2 (and remove any positive flags). Do this only if you want the pure workerd surface.

Checklist

• New project: set compatibility_date to today, skip the flags entirely.
• Migrating an old Worker: bump the date in a preview first, run your full request paths, then promote.
• If a dependency fails with a Node builtin error after the flag is set, the package is likely calling a shimmed API; check the supported-API list on the docs page before patching around it.

When to use

You hit exactly this: Workers: Node.js compat flags and compatibility_date, done right in Workers.

When not to use

A different error, or the same symptom in a different tool. This page only covers the failure above.

Compatibility

Workers (versions mentioned here: V8).

Verified against the live Node.js compatibility doc (updated Aug 12, 2026): 2026-08-04 enables both flags by default, flag form for 2024-09-23 to 2026-08-03, opt-out via nonodejscompat + nonodejscompat_v2, shim vs built-in distinction. Ref: https://developers.cloudflare.com/workers/runtime-apis/nodejs/

Not specified by the original author.

TL;DR: Check the compatibility_date first. For dates # Node builtin errors in Workers builds The errors look like process is not defined

Node builtin errors in Workers builds

The errors look like process is not defined, Buffer is not defined, or Dynamic require of "buffer" is not supported. They share one root cause: code (yours or a dependency's) touches a Node.js builtin that is not available in the workerd runtime.

Diagnose in order

1. Check the compatibility_date first. For dates 2026-08-04 or later, nodejs_compat and nodejs_compat_v2 are on by default and real Node builtins are available. For 2024-09-23 to 2026-08-03, add "nodejs_compat" to compatibility_flags. For older dates, bump the date; do not patch the package first.
2. Built-in vs shim. With the flag on, some Node APIs are full runtime implementations and some are Wrangler-added polyfill shims. Shims let the import succeed but throw when called. If the error moved from build time to runtime after enabling the flag, you are calling a shimmed API: check the supported Node.js APIs list and replace the call.
3. Bundler shims. process is not defined in a Vite build usually means a dependency references process.env and the bundler did not define it. The Vite plugin / Wrangler define some of these, but a library reaching for process directly needs the compat flag plus, sometimes, an explicit define in build config.

The traps

• Adding the flag to fix a build error, then shipping without testing the runtime path: the shim throws in production instead.
• require() of Node builtins in ESM Workers: use node: prefixed imports so the bundler routes them to the runtime implementations.

Checklist

• Reproduce with the compat date current before touching dependencies.
• If a dependency fundamentally needs unsupported Node APIs (child_process, native addons), it cannot run on Workers; find an alternative or move that code to a container/VM.

When to use

You hit exactly this: Workers build errors: Node builtins that do not exist at runtime in Workers build errors.

When not to use

A different error, or the same symptom in a different tool. This page only covers the failure above.

Compatibility

Workers build errors.

Edge cases

• For older dates, bump the date; do not patch the package first.

Verified against the live Node.js compatibility doc: default-on dates, flag form for 2024-09-23 to 2026-08-03, built-in vs polyfill-shim distinction (shims throw at runtime). Ref: https://developers.cloudflare.com/workers/runtime-apis/nodejs/