workerd error: assets binding 404 on spa fallback

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.