Debugging Cloudflare Pages from artifact to custom-domain cache

A successful Cloudflare Pages deployment proves that the build and deploy pipeline accepted an artifact. It does not prove that a custom domain serves the same content. Failure can occur during dependency installation, build, output selection, Functions, Pages deployment, DNS or TLS, zone rules, or cache. Debug each layer in order instead of attributing every symptom to the CDN. As of 2026-07-29, Cloudflare's debugging guide still begins with the deployment build log and explains that a proxied custom domain receives zone settings that do not affect the pages.dev domain. The Redirects documentation also says _redirects rules do not apply to requests served by Pages Functions, so Functions routing can override an expected SPA fallback or redirect. Implementation steps Freeze the incident inputs: expected commit SHA, Pages project, branch, build ID, command, output directory, Node and package-manager versions, affected URL, and first observed time. Do not immediately redeploy. The original log and artifact are evidence. Reproduce locally using the lockfile, the same command, and the same environment mode. Confirm that the output root contains index.html , hashed assets, _redirects , _headers , robots, and sitemap as expected. Vite commonly emits dist , but the actual configuration is authoritative. npm ci npm run build find dist -maxdepth 2 -type f | sort | sed -n '1,120p' test -f dist/index.html Read the Cloudflare build log and classify the failure as initialization, build, or global deployment. An install failure points to runtime, lockfile, or a private registry. A build failure often reflects an environment name or secret available in only preview or production. A deploy failure can involve Functions or project configuration. Never paste secret values into an issue. Verify the deployment-specific *.pages.dev URL before the custom domain. Test home, hashed JavaScript and CSS, deep routes, API or Functions, 404, robots and sitemap, and a version marker. If pages.dev is wrong, the artifact or Pages project is wrong; DNS is not the cause. Only after pages.dev succeeds, inspect the custom domain. Compare DNS, status, Location, ETag, Age, CF-Cache-Status, Content-Type, and a body hash with dig and curl -I . Cloudflare notes that proxied custom domains inherit zone cache and rules. Temporarily switching to DNS-only can isolate the layer, but is not an automatic permanent solution. Inspect routing precedence. _redirects order matters. Test exact rules and wildcards. When a Function captures the route, implement the redirect or fallback in that Function or exclude the route; _redirects will not rescue it. An SPA fallback should not convert missing assets, APIs, and SEO 404s into 200 responses containing index HTML. Address cache last. Use a cache-busting query and compare deployment and custom domains, proving that the origin artifact is fresh while the custom response is stale. Prefer a single-URL or asset purge. Remove or narrow a Cache Everything rule that interferes with Pages. Fetch and hash the response again after purge; a dashboard success message is not final verification. Failure and recovery For a build failure, continue serving the last successful deployment and preserve the new log. Correct runtime, lockfile, or environment configuration in the repository and trigger from a new commit. Avoid repeatedly changing dashboard commands that cannot be reproduced. A pages.dev root 404 often indicates the wrong output directory or missing index.html . Correct project configuration and the artifact instead of hiding it behind a custom redirect. For only deep-route 404s, add a precise SPA fallback and separately test a genuine 404. When a custom domain remains in verification, inspect DNS, Access, redirects, or Workers blocking HTTP validation, plus CAA and zone holds, following Cloudflare's guide. Preserve DNS records before editing; do not delete and recreate production DNS blindly. If an incorrect cache rule serves old HTML referring to deleted hashed assets, roll back to a compatible artifact or purge the HTML, prove all assets return 200, then repair the rule. After rollback, repeat cache-busted live verification on the custom domain. Verification commands curl -sSI https://DEPLOYMENT.pages.dev/ curl -sSI 'https://example.com/?verify=COMMIT_SHA' curl -sS https://DEPLOYMENT.pages.dev/robots.txt | shasum -a 256 curl -sS 'https://example.com/robots.txt?verify=COMMIT_SHA' | shasum -a 256 dig +short example.com Create a table for root, deep route, missing page, hashed asset, redirect, Function, and SEO files. Compare status, content type, location, hash, and cache headers on pages.dev and the custom domain. Use domcontentloaded plus an expected element for browser smoke; do not rely only on networkidle for sites with persistent connections. Primary sources Cloudflare Debugging Pages Cloudflare Pages Redirects Cloudflare Serving Pages Internal links Browse technical articles for React prerendering and the production stack. Practice Pages deployment verification through the course catalog . Share a deployment URL and redacted headers through the contact page .