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

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

deploymentnotfound on Vercel means no deployment is attached to the hostname you opened: the error page shows 404 NOTFOUND with Code DEPLOYMENTNOT_FOUND. The domain was never assigned to the project, the deployment behind the URL was deleted, or the URL is a stale preview link. Fix it by attaching the domain in the project under Settings, Domains, or by promoting a Ready build to Production; redeploying alone does not attach a domain.

404: NOT_FOUND
Code: DEPLOYMENT_NOT_FOUND

Use this when

• A Vercel URL shows 404 NOTFOUND and the code line reads DEPLOYMENTNOT_FOUND
• A custom domain was bought and DNS points at Vercel, but the site never loads
• An old preview or deployment URL that used to work now returns 404

Not for this skill when

• The code is NOTFOUND without DEPLOYMENT in front of it: a deployment is serving but its routes have no match, which is a routing or output problem
• Your own app renders its 404 page: that is your code answering, not Vercel
• The deploy itself failed in the build log: fix the build first, then come back here if the hostname still 404s

Steps

1. Read the code, not just the 404. Open the failing URL and confirm the page shows DEPLOYMENTNOTFOUND, not plain NOT_FOUND.

Expected: you have confirmed which of the two Vercel 404s this is before changing anything.

2. Attach the domain to the project. In the Vercel dashboard open your project, then Settings, then Domains, type the domain and click Add. It takes effect within seconds and does not need a redeploy.

Expected: refreshing the URL loads your site instead of the error page.

3. Check you are opening the right URL. Preview URLs (project-git-branch-team.vercel.app) are ephemeral and die when the branch or project is deleted. Use the production domain, or click Visit on the latest deployment.

Expected: the production URL works even if the bookmarked preview URL does not.

4. Confirm a Ready production deployment exists. Open the Deployments tab. If the latest Production deployment shows Error or Canceled there is nothing to serve; fix the build and redeploy. If a good build exists but is not Production, promote it.

Expected: the Deployments tab shows a Ready build marked Production.

5. If the domain shows as assigned but the error persists, check whose project it is assigned to. A domain can only serve one project; assigned to a different project or team in the same account, it 404s on yours.

Expected: the domain sits on the project you are testing, in the team you are testing.

Variant phrasings

404 notfound code deploymentnot_found

The full error page text as one search string. Same diagnosis and same fix: attach the domain (step 2) or promote a Ready build (step 4).

deployment not found vercel

The plain-words version of the same failure. If Vercel answered the request, the code on the page is DEPLOYMENTNOTFOUND even when the person searching does not quote it.

vercel domain 404 after adding custom domain

Adding DNS records is only half of the setup: until the domain is also added under Settings, Domains on the project, Vercel has nowhere to route it and returns this code.

Root cause

Vercel routes each hostname to one specific deployment. If the domain was never added to the project, was removed, or the deployment the URL pointed at was deleted, the edge has nowhere to send the request and returns DEPLOYMENTNOTFOUND. Redeploying does not attach a domain, which is why people get stuck in a redeploy loop.

Edge cases

• Domain assigned but still 404ing: DNS may still be propagating (up to 24 hours), or the domain is assigned to a different project or team.
• Deployment Protection is on: deployment URLs ask for a Vercel login by design. That is not this error; use the production domain instead.
• The default project.vercel.app name is taken by someone else: pick another project name so the default slug is free.

Tool compatibility

Vercel, all plans (Hobby, Pro, Enterprise), for both vercel.app domains and custom domains. Dashboard steps are the same on every plan.

Related skills

• Vercel Blob client upload: Access denied, provide a valid token - a different Vercel failure, after the deployment itself loads: https://vectle.com/skills/sklk8NXBSuuEqWele64_QODA
• Diagnose timeouts for AI routes deployed on Vercel: https://vectle.com/skills/skl_jxLAo75dHb9lR1SE4WsruQ

Provenance

Built from real deployment writeups documenting this exact failure, linked in the evidence.

Multiple real deployment writeups document this exact failure. One project manual records the troubleshooting entry verbatim: Error: 404: NOT_FOUND Code: DEPLOYMENT_NOT_FOUND, with the diagnosis that DNS is pointing at Vercel fine but Vercel does not know which project to display, and the verified fix: go to the Vercel Dashboard, open the project, Settings -> Domains, type the domain and click Add, then refresh. A second writeup adds the key distinction: read the code on the 404 page, because NOTFOUND means a deployment is serving but the route has no match, while DEPLOYMENTNOTFOUND means no deployment is attached to the hostname at all, fixed by attaching the domain or promoting the right build to Production. Full threads: https://github.com/bgillis99-pixel/final-125111am/blob/HEAD/DEPLOYMENTMANUAL.md and https://github.com/sakshamfit/restaurant/blob/HEAD/DEPLOY.md

Not specified by the original author.

TL;DR: Stop polling and check the deployment state first. A Pages preview URL can 404 forever if the deployment itself failed or the custom domain was never attached, and no amount of waiting fixes that. List deployments with wrangler pages deployment list, confirm the latest is successful, test the pages.dev preview URL directly, and only then look at DNS or domain attachment. Poll the API state, not the URL.

agent timed out waiting for preview URL to propagate after pages deploy failed to attach the route

Steps

1. Stop the polling loop. Run wrangler pages deployment list --project-name=[your-project] and look at the latest deployment's status. Expected: you see SUCCESS, FAILED, or BUILDING with a reason. If it failed, fix the build - waiting was never going to help.
2. Test the pages.dev preview URL for that deployment directly, not the custom domain. Expected: a 200 response. If the preview URL works, the deploy is fine and the problem is purely domain attachment or DNS.
3. Check the custom domain's attachment status in the dashboard or via the API. Expected: the domain shows Active. Anything else - pending, error, unattached - means re-attach it; DNS propagation is irrelevant until this is Active.
4. Only now check DNS: confirm the domain's records point at Pages. Expected: correct records present. Give real propagation a bounded window, but treat the API's domain status as the source of truth, not repeated curl attempts.
5. Replace the open-ended wait with a bounded one: poll the preview URL for at most 5 minutes, then fall back to checking deployment and domain state. Expected: the agent always reports deploy state instead of "still waiting".

Use this when

• a Pages preview URL 404s after deploy
• the custom domain never starts serving after a Pages deploy
• the agent has been polling a URL for many minutes with no 200
• "deploy succeeded but the site isn't live"

Not for this skill when

• the build itself failed - that's a build error, fix the build command
• this is a Workers (non-Pages) route problem - different routing system
• DNS is managed outside Cloudflare and records were never created - create them first
• you need the branch preview URL - make sure preview aliases are enabled for the branch

Variant phrasings

• pages preview deployment returns 404
• custom domain not attached after wrangler pages deploy
• wrangler pages deploy finished but nothing is live
• agent waits forever for preview URL to come up

Why it happens

Pages separates deploying from domain attachment, and agents conflate the two: they watch the custom domain while the deploy failed, or watch the deploy while the domain was never attached. Polling the wrong URL for the wrong state can never succeed, so the wait only ends when the agent's timeout kills it.

Edge cases

• Deleted deployments 404 permanently. Deploy again rather than waiting.
• Branch preview URLs need the branch alias; the production preview URL won't show branch builds.
• Apex domains need special record handling. A CNAME at the apex won't work with most DNS setups.
• A deployment can report SUCCESS while its functions fail at runtime. A 200 on the preview URL is the real check.

Provenance

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

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

Thread query: agent timed out waiting for preview URL to propagate after pages deploy failed to attach the route

TL;DR: