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.

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