Workers static assets: the deploy succeeded, the site did not

What changed

There is no single "static assets changed on date X" event behind this runbook. There are four separate things, in four overlapping version windows, that all end with a green deploy over a wrong site. Keeping them apart is the whole point: each has a different fix, and only two of them are version bugs.

1. What gets uploaded is decided by the build, not by your wrangler config

• The Vite plugin generates the deploy config. On vite build, the plugin writes an output wrangler.json whose assets.directory points at the client build output, so you do not need to set assets.directory in your own config (Cloudflare Vite plugin docs, reviewed 2026-11-08).
• Deploy commands follow a redirect file. wrangler deploy, wrangler dev and wrangler versions upload look up the tree for .wrangler/deploy/config.json and, when it exists, load the configuration that file names instead of the project's own file. Wrangler has supported the redirect since workers-sdk PR #7442 (merged 2025-01-08); the Vite plugin writes the redirect during the build, as described in the deploy flow of issue #15860.
• The failure this enables. If the build did not run, ran in a different directory, or the checkout does not contain the generated output, Wrangler falls back to the project configuration and uploads whatever assets.directory points at — often the source directory that still holds the unbuilt index.html. That is the symptom reported in issue #15860 (inferred from the mechanism; the symptom itself is reviewed).
• The upload is a manifest of path → hash → size. Files whose hashes were already uploaded are not sent again; that deduplication is expected and is not itself an error (Workers static assets direct-upload docs, reviewed 2026-11-08).

2. The SPA fallback regressed in 4.99.0 and was fixed in 4.101.0

• 4.98.0, the version probed as good. With not_found_handling = "single-page-application", an inherited top-level routes block and a named environment, wrangler dev --env <name> returned 200 with index.html for GET /.
• 4.99.0, the regression. The same command returned the Worker's raw 404 for GET /, while /projects and /api/* were unchanged. Both triggers were required: --env and an inherited routes block. Dropping either one restored the old behaviour. Locking back to 4.98.0 was the workaround (workers-sdk issue #14255, opened 2026-06-11).
• Fixed 2026-06-15. PR #14282 ("preserve asset fallback with routes") disabled automatic route matching for the dev server; it first shipped in wrangler 4.101.0. The same regression also affected not_found_handling = "404-page" (comment in #14255).
• This is a dev-server bug, and the deploy-time confusion around it is separate. With the Vite plugin the Cloudflare environment is selected at build time through CLOUDFLARE_ENV; passing it to vite preview or wrangler deploy has no effect (Cloudflare Vite plugin environments docs, reviewed 2026-11-08). "I added --env and it still deployed the other environment" is not #14255.

3. In 4.110.0 a deploy can report success before its assets are actually served

• What was reported. workers-sdk issue #15860, opened 2026-09-25: wrangler 4.110.0, @cloudflare/vite-plugin 1.15.3, Node v26.7.0, Windows 11, the plugin's redirected-config flow. Three times in about a day the Worker served the raw source index.html (referencing /src/react-app/main.tsx) and every hashed JS/CSS asset 404'd — on the workers.dev hostname and both custom domains at once, despite a successful deploy with no warning.
• What preceded it. Two of the three broken deploys were directly preceded by a deploy logging No updated asset files to upload. Proceeding with deployment...; the third uploaded genuinely new assets and still served the broken state, so "skip re-upload" does not explain all of it.
• The cache header. Every broken response carried CF-Cache-Status: HIT. The reporter's own reading is that this does not look like ordinary edge-cache staleness — the body served was never a deployed asset — and suspects the deployment's asset manifest or binding step. Cloudflare has not confirmed a cause (inference, not a documented behaviour).
• State at review. Open, labelled needs-reproduction, package:wrangler and feature:workers-assets, last updated 2026-10-23. A 2026-10-17 comment reports a related shape — zero-byte 404s for every asset on an inactive assets-only version — on wrangler 4.151.0, without ETag, Age or CF-Cache-Status headers.

4. An inherited routes block moves a custom domain on every deploy

• routes is an inheritable key. An env.<name> block that does not override routes inherits the top-level array. When that array contains custom_domain: true, every deploy to the named environment re-asserts the domain on the environment's Worker, and only one Worker can own a custom-domain record.
• The observed effect. workers-sdk issue #13925 (wrangler 4.81.0, opened 2026-05-15, closed 2026-06-03 as a docs/UX issue): wrangler deploy --env staging moved the apex domain from the production Worker to the staging Worker, every time, in both directions. Production traffic then served the staging build.
• The only signal is a normal-looking log line. Each deploy prints Deployed <worker> triggers ... <hostname> (custom domain). Nothing in the output says ownership just changed.
• 4.98.0 added a warning, not a guard. PR #13979 (merged 2026-06-03) makes Wrangler warn: The "env.staging" environment inherits the top-level `routes` configuration, which includes the custom domain(s): <hostname>. Deploying this environment will reassign these custom domains away from the top-level Worker. Add "routes": [] to "env.staging" to prevent inheritance. The deploy still proceeds; "routes": [] in the env block is still the fix.

Version window reviewed:

Reviewed against the versions named in the issues and release notes above. Nothing in this runbook was re-run on a live account at review time — the detection chapter is a reading of the published behaviour, and the appendix marks each claim's source.

Detect: are you affected?

Three read-only checks: your versions, what the public hostname actually serves, and whether that response is the build on your disk. Run them in that order. If all three are clean, stop — this is not the runbook and you should not buy it.

Check 1 — versions, and which window you are in

npx wrangler --version
npm ls wrangler @cloudflare/vite-plugin --depth=0 2>/dev/null | grep -E "wrangler|vite-plugin"

Check 2 — what the public hostname actually serves

Ask for the page and for the first hashed asset it references. Replace $HOST with the hostname your users hit, including any custom domain.

curl -sS -D - -o /dev/null "https://$HOST/"
curl -sS "https://$HOST/" | grep -oE '(/src/[^"]*|/assets/[^"]*\.(js|css))' | head -n 5
ASSET=$(curl -sS "https://$HOST/" | grep -oE '/assets/[^"]+\.(js|css)' | head -n 1)
echo "$ASSET"; curl -sS -o /dev/null -w "%{http_code}\n" "https://$HOST$ASSET"

Check 3 — is the served page the build on this disk?

cat .wrangler/deploy/config.json 2>/dev/null || echo "no redirected config"
curl -sS "https://$HOST/" | sha256sum
sha256sum dist/client/index.html
npx wrangler deployments status --name "$WORKER_NAME"

Exit condition: wrangler outside the 4.99.0–4.110.x window (or on a version whose release notes you have read), check 2 serving your build with no stored copy, and check 3 showing equal hashes. That is a different problem — do not buy this runbook for it.

Failure modes

Six failures are covered by this runbook, each with the error shape, the trigger, the fix and a verification command. Two are visible here: the two that get misdiagnosed as "wrangler is flaky" and "Cloudflare moved my domain".

Migration: what the paid chapter covers

The fix depends on which part of the pipeline you own, so the paid chapter is split that way. A change that repairs the deploy job can still leave a browser on a stored copy, and a config change that fixes staging can move a domain off production.

Includes rollback: which changes are safe to revert alone, which must be reverted together (the deploy and the domain ownership), and what stays broken after a rollback.

Appendix

• workers-sdk issue #15860 — "Deployed Worker intermittently serves unbuilt source index.html + 404s on hashed assets, despite successful wrangler deploy" — opened 2026-09-25, open (needs-reproduction), reviewed 2026-11-08
• workers-sdk issue #14255 — "[[email protected]] not_found_handling SPA fallback no longer rewrites / when --env + inherited [[routes]] are both present" — opened 2026-06-11, closed 2026-06-15, reviewed
• workers-sdk PR #14282 — "fix(wrangler): preserve asset fallback with routes" — merged 2026-06-15; in wrangler 4.101.0 release notes, reviewed
• workers-sdk issue #13925 — "routes inheritance silently transfers ownership of custom domains between env Workers on every deploy" — opened 2026-05-15, closed 2026-06-03, reviewed
• workers-sdk PR #13979 — "warn when named env silently inherits custom_domain routes" — merged 2026-06-03; in wrangler 4.98.0 release notes, reviewed
• Cloudflare docs — Static Assets — routing, caching, not_found_handling; updated 2026-10-12, reviewed
• Cloudflare docs — Vite plugin: Static Assets — generated wrangler.json and assets.directory; updated 2026-10-28, reviewed
• Cloudflare docs — Vite plugin: Cloudflare Environments — CLOUDFLARE_ENV selected at build time; updated 2026-10-12, reviewed
• Cloudflare docs — Workers static assets: Direct Uploads — asset manifest, hashes, deduplication; updated 2026-08-10, reviewed
• Cloudflare docs — Wrangler configuration — inheritable keys, assets defaults; updated 2026-10-29, reviewed
• Cloudflare docs — Wrangler commands — deployments status, deployments list, rollback; updated 2026-04-23, reviewed
• Cloudflare docs — Cache responses — CF-Cache-Status and Age; updated 2026-09-04, reviewed
• workers-sdk PR #7442 — redirect Wrangler to a generated config for deploy commands — merged 2025-01-08, reviewed (mechanism)
• workers-sdk issue #8100 — "vite build without an index.html doesn't copy over assets directory to /dist" — 2025-02-11, @cloudflare/[email protected] era; secondary (error text only)