skip to content

In Cloudflare Workers, an npm SDK reads process.env.API_KEY and gets undefined although the secret is set; why, and what fixes it?

level: seniorimportance: should knowfreq 30%

answer

  1. no OS environment in an isolate
  2. a flag gated by date
  3. 2025-04-01 with Node.js compatibility
  4. text and JSON bindings only

basics

~20 s

process.env is filled from vars, secrets and version metadata only when Node.js compatibility is on and the compatibility date is 2025-04-01 or later (or nodejs_compat_populate_process_env is set). Otherwise it is empty, so move the date, add the flag, or pass env.API_KEY explicitly.

solid answer

~40 s

A Worker has no operating-system environment; configuration arrives as bindings on `env`. The runtime copies bindings into `process.env` only when Node.js compatibility is on and `nodejs_compat_populate_process_env` is on, which Node.js compatibility implies for compatibility dates from 2025-04-01. It copies text and JSON bindings only: vars, secrets and version metadata, never KV or R2 bindings. So an empty value usually means a date before 2025-04-01, a partial opt-out such as `no_nodejs_compat` alone, or `nodejs_compat_do_not_populate_process_env`. Fix it by moving the date, adding the populate flag, or constructing the SDK in the handler with `env.API_KEY`. Remember that `process.env` is shared by every request in the isolate.

code

javascript · 8 lines
javascript
let client;

export default {
  async fetch(request, env) {
    client ??= { apiKey: env.API_KEY, logLevel: env.LOG_LEVEL ?? "info" };
    return Response.json({ configured: Boolean(client.apiKey) });
  },
};

go deeper

for a junior

Recall that Worker configuration arrives on env, and that process.env is only filled when Node.js compatibility and a recent compatibility date allow it.

for a middle

Explain the 2025-04-01 populate rule, which bindings are copied, and why a JSON var arrives in process.env as a string.

for a senior

Diagnose an empty process.env from the date and flags, and avoid the shared-isolate and build-time NODE_ENV traps.

for a principal

Decide whether to let every dependency read secrets through process.env or keep population off and pass credentials explicitly.

## Why a Worker has no process environment In Node.js, `process.env` is a copy of the operating system environment taken when the process started. A Worker has no such thing: it runs in an isolate inside workerd, and configuration reaches it as **bindings** on the `env` argument of its handlers (`fetch(request, env, ctx)`). For a Worker's own code that is the normal path. The problem appears with npm SDKs written for Node.js, which read `process.env.API_KEY` themselves, often at module scope when the client is created. ## When the runtime fills process.env Cloudflare added an automatic bridge, gated like every runtime change: - `process` exists only with **Node.js compatibility** v2 (on by default from compatibility date 2026-08-04, opt-in with `nodejs_compat` before; v1 has no `process` global). - `process.env` is **populated** only when `nodejs_compat_populate_process_env` is on. Node.js compatibility implies it for dates from **2025-04-01**; on earlier dates `process.env` exists but is an empty object. - The values copied are bindings with **text or JSON values**: plaintext `vars`, **secrets**, and the version metadata binding. Resource bindings such as a KV namespace or an R2 bucket never appear. - A JSON var becomes a **JSON string** in `process.env` (`'{"max":5}'`), while `env.LIMITS` is the parsed object. - `process.env` is readable at module scope, so an SDK constructed at the top of the file sees the values. Two flags switch population off: `nodejs_compat_do_not_populate_process_env` keeps `process.env` empty, and `disallow_importable_env` (no default date) blocks both `process.env` population and importing `env` from `cloudflare:workers`. ## Reading the symptom | Configuration | What `process.env.API_KEY` gives | |---|---| | No Node.js compatibility | `ReferenceError: process is not defined` (no global) | | `nodejs_compat`, date before 2024-09-23 | no `process` global (v1); `node:process` imports, with an empty `env` | | `nodejs_compat`, date 2024-09-23 to 2025-03-31 | `undefined`: `process.env` is `{}` | | date from 2026-08-04 with only `no_nodejs_compat` | `undefined`: v2 keeps `process`, population is off | | date from 2025-04-01 with Node.js compatibility | the secret's value | So "the secret exists but the SDK sees `undefined`" almost always means one of three things: a date before 2025-04-01, a partial opt-out, or an explicit do-not-populate flag. Locally, also check that the secret is actually defined for the local run. ## Fixes, from least to most code 1. **Move the date** to 2025-04-01 or later with Node.js compatibility on (or any date from 2026-08-04), after reading what else the bump changes. 2. **Add the flag** `nodejs_compat_populate_process_env` if the date cannot move yet. 3. **Pass the value explicitly**: construct the SDK client inside the handler with `env.API_KEY`. This works on any date and keeps configuration flowing through bindings. 4. For module-level access to bindings, importing `env` from `cloudflare:workers` is the Workers-native route. ## Confirming it quickly A two-line probe settles the question faster than reading flags: return `Object.keys(process.env)` and `typeof globalThis.process` from a test route and run it under `wrangler dev` with the Worker's real date and flags. An empty list with `process` present points at population (date or flag); a missing `process` points at Node.js compatibility itself. The same probe also shows that a JSON var arrives as a string, so code that reads `process.env.LIMITS` must `JSON.parse` it, while `env.LIMITS` is already an object. Remove the probe before deploying, since it would list the names of the Worker's secrets to anyone who calls it. ## Traps once it works - **Shared per isolate.** `process.env` is one object for every request the isolate serves. Writing a per-request value into it, such as a tenant's token, leaks that value into concurrent and later requests. Treat it as read-only configuration. - **Do not replace it.** Assigning `process.env = env` breaks the link with `import { env } from "node:process"`, and every value set earlier is lost. - **`NODE_ENV` is not a runtime value.** Wrangler replaces `process.env.NODE_ENV` in the bundle at build time: `"development"` under `wrangler dev`, `"production"` for `wrangler deploy`, overridable by setting `NODE_ENV` in the shell running Wrangler. A var named `NODE_ENV` cannot change code that was already rewritten. - **Secrets become reachable by every library.** Once population is on, any dependency can read every secret through `process.env`, just as in Node.js. A team that does not want that keeps population off and passes credentials explicitly.

  • Why must a Worker never write a per-request value into process.env?
    `process.env` is one object shared by every request that the isolate serves, not a per-request copy. A tenant token written there is visible to concurrent and later requests on the same isolate, which leaks data between users. Keep request-scoped values in local variables or pass them explicitly, and treat `process.env` as read-only configuration.
  • A team sets a var named NODE_ENV to staging, but code checking process.env.NODE_ENV still sees production. Why?
    Wrangler replaces `process.env.NODE_ENV` in the bundle at build time: `"development"` under `wrangler dev` and `"production"` for `wrangler deploy`. The comparison is already a literal in the deployed code, so a runtime var cannot change it. Set `NODE_ENV=staging` in the shell that runs Wrangler instead.

  • Every binding, including KV namespaces, is copied into process.env.
  • process.env in a Worker is a snapshot of the deploy machine's environment.
  • process.env is isolated per request, so writing to it is safe.
  • A JSON var shows up in process.env as a parsed object.
  • Setting a NODE_ENV var changes process.env.NODE_ENV checks at runtime.

Assumes Cloudflare Workers as of 2026-10-10: process.env population is implied by Node.js compatibility for dates from 2025-04-01, and Node.js compatibility is on by default from 2026-08-04.