Skip to content
Cade's Dotfiles

Cloudflare Pages build failing

Page source

Source: Troubleshooting reference

Check the build log via the API:

Terminal window
ACCOUNT="YOUR_CLOUDFLARE_ACCOUNT_ID"
TOKEN="..."
# List recent deployments
curl -s "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT/pages/projects/dotfiles/deployments" \
  -H "Authorization: Bearer $TOKEN" | python3 -m json.tool | grep -E '"id"|"status"'


# Get logs for a specific deployment
DEPLOY_ID="..."
curl -s "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT/pages/projects/dotfiles/deployments/$DEPLOY_ID/history/logs" \
  -H "Authorization: Bearer $TOKEN" | python3 -c "
import sys, json
for e in json.load(sys.stdin)['result']['data']: print(e['line'])
"

Common causes:

  • Unsupported Node version — the handbook requires Node 22.12 or newer; CI selects Node 24. Check the build environment and site/package.json.
  • Chromium executable missing — Mermaid renders during the build. Install the matching browser with npx --prefix site --no-install playwright install chromium; keep PLAYWRIGHT_BROWSERS_PATH identical for installation and the build.
  • Invalid link or missing feature coverage — run ./tests/ci.sh docs, then fix the named Markdown link, source path, or explicit entry in docs/_data/features.json. Do not disable the checker.
  • Build output not found — confirm destination_dir = "site/dist" in infra/cloudflare/main.tf. The Astro build is verified before upload.