skip to content

A Cloudflare Worker that redirects visitors by country sometimes sends one user to another country's site under load; how can module-scope state cause this?

level: seniorimportance: must knowfreq 60%

answer

  1. one isolate, many requests
  2. await hands the thread over
  3. shared variable, last writer wins
  4. request-bound I/O objects

basics

~20 s

One Workers isolate serves many requests at once, and module-scope variables are shared by all of them. If the handler stores the visitor's country in one and then awaits, another request overwrites it before the first reads it back.

solid answer

~50 s

Cloudflare reuses an isolate for many requests, including concurrent ones on its single-threaded event loop. Code outside the handler runs once per isolate, so a `let country` declared at module scope is one variable shared by every request that isolate serves. The handler sets `country = request.cf.country`, then awaits a KV read; while it waits, another visitor's request runs and overwrites `country`, so the first request builds its redirect from the wrong value. It looks random because it needs two requests in flight on one isolate, which is why it shows up only under load. The fix is to keep request data in local variables or arguments. Module scope is fine for immutable data you can rebuild, but never for per-user state, and never for anything you need to survive: an isolate can be evicted at any time.

code

javascript · 12 lines
javascript
// Module scope: every request this isolate serves shares this variable.
let country;

export default {
  async fetch(request, env) {
    country = request.cf?.country ?? "XX";
    // While this KV read is in flight, the isolate runs other requests,
    // and any of them can overwrite `country`.
    const paths = (await env.REDIRECTS.get("paths", "json")) ?? {};
    return Response.redirect(`https://shop.example.com${paths[country] ?? "/intl/"}`, 302);
  },
};

go deeper

for a junior

Remember that top-level code runs once per isolate and its variables are shared by every request that isolate serves; request data belongs inside the handler.

for a middle

Explain how an await lets another request run on the same isolate, why that makes a shared variable last-writer-wins, and why isolates can be evicted at any time.

for a senior

Diagnose the symptom from production behaviour: intermittent, load-dependent, wrong-user data. Find module-level lets, recognise the cross-request I/O error, and prove the fix with concurrent tests.

for a principal

Set a review rule for Worker code: no mutable module state without a written reason, per-user state only in a real store, and concurrency tests for anything cached at module scope.

## One isolate, many requests A Cloudflare Worker runs inside a **V8 isolate**: a lightweight sandbox with its own JavaScript heap, created inside a runtime process that hosts many other isolates. Cloudflare does not create a fresh isolate per request. The same isolate handles request after request, and, like other JavaScript runtimes, it can handle **several requests concurrently** on one single-threaded event loop. Whenever a request's code reaches an `await` on I/O, such as `fetch()`, a KV read or a database call, the event loop is free to run another request's code until the I/O completes. Code at the top level of the module, outside `export default { fetch }`, runs once when the isolate loads. Every variable declared there is therefore shared by every request that isolate will ever serve. ## How the leak happens Take a geolocation redirect Worker that writes the visitor's country into a module-level `let country` and then reads a redirect map from Workers KV: 1. Request A from a visitor in Germany sets `country` to `"DE"` and awaits the KV read. 2. While A waits, request B from France arrives on the same isolate and sets `country` to `"FR"`, then awaits its own read. 3. A's read completes. A now reads `country`, gets `"FR"`, and redirects the German visitor to the French site. Nothing throws. The bug needs two requests overlapping on one isolate, so it never shows when one developer clicks through a local `wrangler dev` session and appears only under real traffic. Fire a few concurrent requests with different countries at the buggy version locally and every one of them follows whichever request wrote last. ## What module scope is good for | Kept in module scope | Safe? | Why | |---|---|---| | The visitor's country, user ID or session | No | Shared by concurrent requests; one overwrites another | | A per-request counter or accumulator | No | Mixes requests and resets whenever the isolate is replaced | | A compiled regular expression or parsed static config | Yes | Identical for every request and cheap to rebuild | | A small cache of data that may be stale | With care | Lost on eviction, separate per isolate, counts against 128 MB | | A `Response`, `Request` or stream from an earlier request | No | The runtime refuses cross-request I/O | Two facts set the limits of the "with care" row: - **Isolates are not long-lived.** Cloudflare may evict one because of resource pressure on the machine, a suspicious script, or the Worker hitting its own resource limits, and nothing guarantees that two requests reach the same or a different isolate. Module scope is a best-effort cache, never storage. - **Every isolate has its own copy.** Different locations and different isolates in one location do not share module state, so a module-level counter does not count the Worker's traffic. ## The runtime's own guard on I/O objects The Workers runtime enforces one boundary itself. I/O objects, meaning streams, request and response bodies and similar handles, belong to the request that created them. Keep a `fetch()` response in a module variable and read its body from a later request, and the runtime throws: `Cannot perform I/O on behalf of a different request. I/O objects (such as streams, request/response bodies, and others) created in the context of one request handler cannot be accessed from a different request's handler.` That error in production logs is a strong hint that something request-scoped has leaked into module scope. ## Fixing and reviewing it - Declare request data with `const` inside the handler and pass it down as arguments. - Search the module's top level for `let` and `var`; each one needs a reason that holds under concurrency. - Keep per-user or cross-request state in a store built for it, such as KV, D1 or a Durable Object, not in the isolate. - Test with concurrent requests, not sequential clicks, before trusting a fix. A simple reproduction under `wrangler dev` is enough to prove both the bug and the fix: send half a dozen requests at once that carry different countries, with a short await inside the handler so they overlap, and compare each redirect with the country that request sent. The buggy version returns the last writer's redirect to everyone; the version with a local `const` returns each visitor's own. Local mode cannot show isolate eviction or how production spreads traffic across isolates, but it does run concurrent requests through one isolate, which is all this bug needs.

  • Is caching a parsed configuration object in module scope ever acceptable in a Worker?
    Yes, when it is identical for every request and cheap to rebuild. Treat it as a best-effort cache: it vanishes whenever the isolate is evicted, every isolate keeps its own copy, and its size counts against the isolate's 128 MB memory limit, which all concurrent requests share. Never cache anything user-specific there.
  • What happens if a Worker keeps a fetch() Response in a module-level variable and reads its body during a later request?
    The read throws `Cannot perform I/O on behalf of a different request`. The Workers runtime binds streams and request or response bodies to the request context that created them, so a later request cannot touch them. Read the body inside the original request and cache the resulting plain value instead.

  • Each request gets a fresh isolate, so module-level variables reset per request.
  • JavaScript is single-threaded, so two requests can never interleave inside one Worker.
  • A module-level counter gives an accurate count of the Worker's total traffic.
  • An isolate lives as long as the deployment, so module state is durable.
  • Storing the current user in a global is safe if the handler is short.