During a 50% gradual deployment of a Cloudflare Worker serving a single-page app from static assets, some users get 404s for hashed JavaScript files; why, and what fixes it?
answer
- each request routed on its own
- HTML from one version, script from another
- a stable key per user
- affinity is not an override
basics
~20 sA Cloudflare Workers split routes every request independently, so a page's HTML can come from one version and its hashed script from the other, which lacks that file. A stable Cloudflare-Workers-Version-Key header keeps each user on one version.
solid answer
~40 sThis is **version skew**. By default each request in a gradual deployment is assigned a version at random by percentage, so the HTML from version A references `index-a1b2.js` while the follow-up request hits version B, which only has its own hashed file. The fix is **version affinity**: set `Cloudflare-Workers-Version-Key` to a stable identifier such as a user ID cookie, session ID or `ip.src`, usually with a request-header Transform Rule on the zone (not available on `workers.dev`). The platform hashes the key with the percentages, and users on the new version stay there as it grows. `Cloudflare-Workers-Version-Overrides` is different: it pins test requests to an exact deployed version ID. Durable Object instances are already assigned one version per deployment.
go deeper
Know that during a split two versions serve at once, so a page can mix files from both unless something pins the user.
Explain per-request random routing and how Cloudflare-Workers-Version-Key makes the assignment deterministic per user.
Diagnose the 404s from the asset names, pick the right key for the app, say where the header is set, and separate affinity from overrides and Durable Object pinning.
Decide whether every user-facing Worker with hashed assets must ship a version key before it may use gradual deployments, and how skew is monitored.
## The symptom `orders-api` is now a full-stack Worker: it serves a single-page app from **Workers static assets** and the API from the same Worker. The build tool emits content-hashed file names, so each release has its own `index-<hash>.js`. During a 50/50 gradual deployment, some users see a blank page, and the analytics show 404 responses for `.js` files that exist, just not in the version that answered. ## Why it happens: routing is per request In a Cloudflare Workers gradual deployment, **each request is routed to a version independently**, at random, weighted by the deployment's percentages. Nothing ties consecutive requests from one browser together by default. So: 1. The HTML request lands on version A, whose HTML references `assets/index-a1b2c3d4.js`. 2. The browser's next request, for that script, lands on version B. 3. Version B's assets contain `index-m3n4o5p6.js` instead, so the file is not found. Cloudflare calls this **version skew**. It also appears between Workers: when `orders-api` calls a downstream Worker through a service binding, that Worker may be in its own rollout, and the call can land on a downstream version with a different contract. ## The fix: version affinity Set the `Cloudflare-Workers-Version-Key` request header to a **stable identifier**. For a given deployment, every request with the same key is handled by the same version. The platform hashes the key and combines it with the configured percentages; you do not choose which version a key gets. Affinity also behaves well as the rollout progresses. When the new version's share rises from 10% to 20% to 50%, users already assigned to it stay there, and users on the old version move across progressively. They do not flip back unless you roll back. Choosing the key: - **Authenticated apps:** a user ID from a cookie or header, which stays the same across sessions and devices. - **Session-based apps:** a session ID, consistent until the session is replaced. - **Anonymous apps:** the client IP (`ip.src`), which groups users behind the same NAT; or a long-lived random cookie the Worker sets on the first response. Where the header comes from matters. On a zone you control, a request-header Transform Rule can set it from a cookie or `ip.src` without code changes. Transform Rules are not available for `*.workers.dev`, so there the header must come from the client or from an upstream Worker calling over a service binding. The very first request from a new anonymous user is still random until the cookie exists. ## Overrides are not affinity `Cloudflare-Workers-Version-Overrides` is a different header with a different job. Its value names a Worker and an exact version ID (`orders-api="<version id>"`), and it is meant for **testers and smoke tests**, not end-user routing. It only works for a version that is in the current deployment, possibly at 0%. If it cannot be applied (the version is not deployed, or the header is not a valid structured-header dictionary), the request silently falls back to the percentages. Overrides also help with skew **between** Workers: an upstream Worker can pin a downstream Worker's version on a subrequest. That works only for `fetch()` calls over a service binding, because RPC method calls cannot carry headers. | Header | Value | Purpose | |---|---|---| | `Cloudflare-Workers-Version-Key` | Any stable string | Keep one user on one version for the rollout | | `Cloudflare-Workers-Version-Overrides` | `worker-name="<version id>"` | Send a test request to an exact deployed version | ## Durable Objects are already pinned A Worker that implements Durable Objects behaves differently: each object instance is **assigned one version for the whole deployment**, because only one version of a given object may run at a time. As the percentage rises, objects already on the new version stay there, and an object is reset only when its assigned version changes. Requests from the Worker to an object can still be on a different version from the object, so the Worker-to-object API must stay compatible in both directions. ## What to watch During any rollout of a Worker with hashed assets, watch the 404 rate on `.js`, `.css` and image requests per version. Returning the version ID from the version metadata binding in a response header makes skew easy to spot in a browser. If 404s appear anyway, `wrangler rollback` returns the stable version to 100% while the key is fixed.
- How do you keep a call from orders-api to a downstream Worker on a compatible version while both are mid-rollout?Set `Cloudflare-Workers-Version-Overrides` on the subrequest, naming the downstream Worker and the version ID to use; forwarding the original request carries an inbound override through. It works only for `fetch()` calls over the service binding, because RPC method calls cannot attach headers. Keeping both contracts backward compatible avoids needing it.
- Why can't a Transform Rule set the version key for a Worker served only on workers.dev?Transform Rules run on a zone you control, and `*.workers.dev` hostnames are not your zone. There the `Cloudflare-Workers-Version-Key` header has to be set by the client or by an upstream Worker calling over a service binding.
- A gradual deployment keeps each browser on one version by default.
- Cloudflare-Workers-Version-Overrides is the right header for routing real users.
- With a version key, users can bounce between versions as the percentage rises.
- Two versions of one Durable Object instance can run side by side during a split.
- Version overrides work on RPC calls over a service binding as well as fetch().