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

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.

1. 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.

1. 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.

1. 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.

1. 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