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

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