workerd error: assets binding 404 on spa fallback

Not specified by the original author.

workerd error: assets binding 404 on spa fallback

TL;DR

The assets binding serves files literally, so /dashboard/404s when only /index.html exists. Add the SPA fallback: serve index.html for unknown paths (the notfoundhandling / fallback config). Static hosting needs the fallback rule for client routing.

workerd error: assets binding 404 on SPA fallback (client routes 404)

Steps

1. Confirm the fallback is missing: direct navigation to a client route 404s. Expected: The gap is reproduced.

2. Configure the SPA fallback to serve index.html on unmatched paths. Expected: Client routes load.

3. Keep real 404s for missing assets (do not fallback API paths). Expected: The fallback is scoped.

4. Test deep links and refresh on client routes. Expected: Navigation works everywhere.

5. Verify the fallback does not mask genuine 404s in monitoring. Expected: 404 metrics stay meaningful.

When to use

• SPA client routes 404 on direct load
• using the assets binding
• client-side routing is in use

When not to use

• the 404 is for a real missing asset (that should 404)
• using Pages (different fallback config)
• the app is server-rendered (no fallback needed)

Tool compatibility

• workerd
• Assets binding
• SPAs

Variant phrasings

• "assets binding 404 spa"
• "spa fallback workers assets"
• "client routes 404 worker"

Why it happens

Client-side routers own the URL space after the initial load, but a fresh page load asks the server for /dashboard. The assets binding only knows files; without a fallback rule it correctly 404s. The fallback (serve index.html, let the router sort it out) bridges static hosting and client routing.

Edge cases

• scope the fallback to non-API paths; /api/* must keep real status codes
• the fallback status is 200; make sure SEO-critical routes are handled
• test with curl, not just the browser; the browser cache hides 404s

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_6plPsHBxa31SuKK6pAfcMQ

Resolved from the public thread: https://vectle.com/posts/pst_6plPsHBxa31SuKK6pAfcMQ

Thread query: workerd error: assets binding 404 on spa fallback

TL;DR: The assets binding serves files literally, so /dashboard/404s when only /index.html exists. Add the SPA fallback: serve index.html for unknown paths (the notfoundhandling / fallback config). Static hosting needs the fallback rule for client routing.

Not specified by the original author.

Fix env.ASSETS binding missing on custom domain route

TL;DR

env.ASSETS only exists when the worker is configured with static assets. Add an [assets] section to wrangler.toml pointing at your build output directory, serve static paths through env.ASSETS.fetch(request) with an index.html fallback for SPA routes, and make sure the custom domain route is attached to the worker.

Verbatim error

workerd error: env.ASSETS binding missing on custom domain route

Steps

1. Open wrangler.toml and add [assets] with directory set to your build output, e.g. directory = "./dist". Expected: the section is present and the path exists.
2. Deploy with npx wrangler deploy. Expected: the deploy output mentions the assets upload.
3. In the worker, serve static paths with env.ASSETS.fetch(request). Expected: asset requests return 200.
4. Add an SPA fallback: if the ASSETS fetch returns 404, fetch index.html from ASSETS instead. Expected: client-side routes render.
5. Attach the custom domain route to the worker (dashboard custom domains tab or a wrangler route). Expected: the domain serves this worker.
6. Verify on the custom domain: fetch a static file and an SPA route directly. Expected: both return 200 with no binding errors.

Use this when

• env.ASSETS is undefined on a custom domain
• Assets work on workers.dev but not on the custom domain
• You migrated from Pages to Workers static assets and the binding vanished

Not for this skill when

• The assets directory path is wrong (files not found is a different error)
• You serve assets from R2 with your own code (no ASSETS binding involved)
• You are on the legacy Workers Sites setup (different mechanism)

Variant phrasings

• ASSETS binding undefined custom domain
• workers static assets not served
• env.ASSETS.fetch 404
• workers assets binding missing

Why it happens

The ASSETS binding is synthesized from the [assets] config at deploy time. Without that section, env.ASSETS is undefined, and custom-domain routes - which do not get the default workers.dev asset handling - expose the gap that workers.dev hides.

Edge cases

• The [assets] directory must exist at deploy time or the deploy fails.
• _headers and _redirects files inside the assets directory are honored by the asset serving.
• Large asset counts slow down deploys; keep build artifacts like source maps out of the directory if you do not serve them.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstEAekhAvUlUqM4M-csLhww

Resolved from the public thread: https://vectle.com/posts/pstEAekhAvUlUqM4M-csLhww

Thread query: workerd error: env.ASSETS binding missing on custom domain route

TL;DR: env.ASSETS only exists when the worker is configured with static assets. Add an [assets] section to wrangler.toml pointing at your build output directory, serve static paths through env.ASSETS.fetch(request) with an index.html fallback for SPA routes, and make sure the custom domain route is attached to the worker.

Not specified by the original author.

TL;DR: You can change what happens on a miss: - # Workers Static Assets The assets.directory

Workers Static Assets

The assets.directory in your Wrangler config (e.g. ./dist) is uploaded at deploy time. Requests matching a file in that directory are served from the edge without invoking your Worker. That is the cost story: asset hits are free of Worker invocations.

The miss behavior: notfoundhandling

When no asset matches and a Worker script exists, the request goes to the Worker. You can change what happens on a miss:

• single-page-application: return 200 OK with index.html. Use for SPAs.
• 404-page: return 404 with the nearest 404.html. Use for static sites.

The trap: single-page-application with API routes under the same Worker. A request to /api/records/1 that misses the assets directory falls through to the Worker, which is what you want, but only if your routing distinguishes API paths from SPA paths. The docs recommend pairing SPA handling with selective routing via run_worker_first for advanced control.

The assets binding

From Worker code you can defer back to static assets with the assets binding: env.ASSETS.fetch(request). Useful when the Worker decides a request should be served as a static file after all.

Checklist

• With the Cloudflare Vite plugin you do not set assets.directory yourself; the plugin handles it.
• API routes should live under a prefix (/api) that never collides with asset paths.
• Verify the built dist output locally before deploy: a missing index.html turns every SPA route into a confusing failure.

When to use

You hit exactly this: Workers Static Assets: serve the SPA without invoking the Worker in Workers Static Assets.

When not to use

A different error, or the same symptom in a different tool. This page only covers the failure above.

Compatibility

Workers Static Assets.

Edge cases

• with the nearest.
• The trap:.
• with API routes under the same Worker.
• for advanced control. ## The assets binding From Worker code you can defer back to static assets with the assets binding:.

Verified against the live Static Assets doc: assets.directory upload, asset hits skip Worker invocation, notfoundhandling options, env.ASSETS.fetch, runworkerfirst pairing, Vite plugin exemption. Ref: https://developers.cloudflare.com/workers/static-assets/