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

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

The deploy uploaded the worker but attached no route, so there is nothing serving the URL you are hitting. Check the deploy output for the routes it published, add the missing route (or enable workers.dev) in wrangler.toml, and redeploy. A successful upload with zero routes always 404s everywhere except the raw workers.dev subdomain, and that only if workers.dev is enabled.

workerd: preview URL returns 404, deploy failed to attach route

1. Read the last deploy output carefully, looking for the published routes section:

wrangler deploy

Expected: output lists the worker name, version, and one or more routes or the workers.dev URL. If it lists no routes, that is the diagnosis confirmed.

2. Check whether workers.dev is enabled. In wrangler.toml, workers_dev = true gives you YOUR-WORKER.YOUR-SUBDOMAIN.workers.dev. If it is false or missing and you have no custom routes, the worker is reachable nowhere.

Expected: you know which URLs should exist. Enable workers_dev or add routes accordingly.

3. If you expect a custom domain or path, verify the routes table in wrangler.toml:

[[routes]]
pattern = "example.com/api/*"
zone_name = "example.com"

Expected: the pattern covers the URL you are testing. A pattern of example.com/* will not match www.example.com, and zone mismatches silently attach nothing.

4. Redeploy and confirm the routes appear in the output:

wrangler deploy

Expected: the deploy output now lists the route(s). The dashboard worker page shows them under Triggers/Routes.

5. Hit the URL again, and also hit the workers.dev URL as a control.

Expected: workers.dev responds (proves the worker runs), and the custom route responds too (proves routing attached). If workers.dev works but the custom route 404s, the DNS or zone config is wrong, not the worker.

Use this when

• wrangler deploy says success but every URL 404s.
• The dashboard shows the worker with no routes attached.
• You added the worker to a new domain or changed route patterns recently.

Not for this skill when

• The URL returns a 5xx or an error from your code. The route attached fine; the worker itself is crashing.
• The URL returns a Cloudflare 404 page mentioning the zone. DNS is not pointing at Cloudflare; fix DNS.
• wrangler dev (local) 404s. That is a local routing question, not a deploy route question.

Variant phrasings

• workers.dev 404 after deploy
• cloudflare worker deployed but route not working
• wrangler deploy success but URL not found
• worker has no routes after deploy

Why it happens

Uploading a worker and routing traffic to it are two separate steps. wrangler deploy does both only when the config tells it to: workers_dev = true for the workers.dev subdomain, or [[routes]] entries for custom domains. If neither is configured (a fresh project, a copied toml with routes stripped, an env block missing its routes), the upload succeeds and the worker sits idle with no ingress. The 404 comes from the edge having no worker mapped to that hostname, which looks like a broken deploy but is really a missing route.

Edge cases

• Named environments need their own routes. The top-level routes do not automatically apply to --env staging; each env block needs its routes or workers_dev setting.
• Route patterns are matched longest-prefix. A broader pattern on another worker can steal traffic; check for overlapping patterns across workers in the same zone.
• DNS propagation: a correct route on a domain whose DNS is not yet on Cloudflare still 404s. Verify the zone is active in the dashboard.
• Deleting and recreating a worker keeps old routes only if they are in the config. A redeploy from a different machine with a different toml can silently drop routes.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_2l3eqEhuH9ywm-MyX53v6Q

Resolved from the public thread: https://vectle.com/posts/pst_2l3eqEhuH9ywm-MyX53v6Q

Thread query: workerd: preview URL returns 404, deploy failed to attach route

TL;DR:

Not specified by the original author.

TL;DR

Cloudflare validates that the custom domain's DNS actually resolves before it lets a worker claim the route. If the domain has no DNS record, points nowhere, or the zone is not active on Cloudflare, the deploy is rejected with origindnserror. Create the DNS record (or activate the zone), wait for propagation, and redeploy.

The query

wrangler deploy failed: workers.api.error.origin_dns_error on custom domain route

Use this when

• wrangler deploy fails naming origindnserror.
• The route uses a custom domain rather than workers.dev.
• The domain was just registered or just transferred.

Not for

• 'Worker route already exists' (route conflict, separate fix).
• Zone permission errors (token scope problem).
• Runtime 5xx from the origin after a successful deploy (origin health problem).

Steps

Step 1: Check the domain resolves at all

dig +short [domain] A
dig +short [domain] AAAA

Expected result: at least one answer. No answers means there is no DNS record, and no record means the route cannot validate. Create an A, AAAA, or CNAME record for the domain.

Step 2: Confirm the zone is active on Cloudflare

In the dashboard, check the domain's zone status. A zone stuck in 'pending' (nameservers not yet pointed at Cloudflare) fails route validation even with correct records.

Expected result: zone status 'active'. If pending, finish the nameserver change at the registrar first.

Step 3: Check the route pattern matches the record

routes = [
  { pattern = "[domain]/*", zone_name = "[domain]" },
]

Expected result: the pattern's hostname matches the DNS record's hostname. A route for www.[domain] with only an apex record fails validation.

Step 4: Wait for DNS propagation, then redeploy

DNS changes can take minutes to hours to be visible to Cloudflare's validators. Verify with an external resolver before redeploying.

Expected result: the record is visible globally, and the redeploy passes validation.

Step 5: Redeploy

npx wrangler deploy

Expected result: the deploy attaches the route without the DNS error.

Why it happens

Route attachment is a claim on traffic. Cloudflare refuses to route a domain to a worker when the domain does not resolve, because the route would be dead on arrival and the failure would look like a worker outage. The check runs at deploy time, so DNS problems surface as deploy errors rather than runtime errors.

Edge cases

• Proxied (orange-cloud) records validate differently from DNS-only records. For worker routes, the record usually needs to exist; the proxy setting matters for traffic flow after validation.
• Subdomain routes need their own records. An apex record does not cover api.[domain].
• Recently transferred domains can have stale glue at the registry. The zone looks right in the dashboard but resolvers disagree; check with multiple public resolvers.
• Removing the DNS record after a successful deploy does not detach the route, but the next deploy re-validates and fails. Keep the record for the life of the route.

Provenance

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

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

Thread query: wrangler deploy failed: workers.api.error.origindnserror on custom domain route

TL;DR: Cloudflare validates that the custom domain's DNS actually resolves before it lets a worker claim the route. If the domain has no DNS record, points nowhere, or the zone is not active on Cloudflare, the deploy is rejected with origindnserror. Create the DNS record (or activate the zone), wait for propagation, and redeploy.