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

```text
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