Troubleshooting
Diagnose local state, Content Collections, D1 migrations, provider credentials, hydration, CI, custom domains, and Worker deployment.
Content Collections types are missing
A clean clone generates Content Collections during the Vite build. Run:
pnpm build
pnpm checkCI intentionally builds before the standalone type gate.
Local database state is stale
Stop the dev server, inspect .wrangler/state, and reapply migrations:
pnpm db:migrate:localThe E2E preparation script clears isolated D1, R2, and KV state before acceptance.
A form appears clickable but nothing happens
JavaScript-only submit buttons should remain disabled until React hydration. If you add a custom native submit control, apply the same hydration boundary or provide a real server form action.
A responsive utility loses to another class
Use the shared cn() helper. It applies tailwind-merge, so conflicting utilities such as inline-flex and hidden sm:inline-flex resolve predictably.
Email preview works but production fails
Check that MAIL_PREVIEW=false, the selected provider has all required credentials, the sender is verified, and the production domain matches auth-generated links. For SES, verify the region and sandbox state.
Webhooks return invalid signature
Confirm the provider endpoint uses the raw request body and the correct production webhook secret. Do not JSON-parse before verification.
Custom domain deploys but local DNS is stale
The setup CLI can verify through Cloudflare DNS-over-HTTPS while preserving TLS and SNI. Also inspect the Cloudflare custom-domain route and certificate status.
GitHub Actions passes locally but fails remotely
Run the same sequence as CI: install, build, check, browser install, and E2E. Avoid reusing a running dev server. Keep Playwright at one worker for shared local Cloudflare state.
Worker bundle or type generation fails
pnpm cf-typegen
pnpm exec wrangler deploy --dry-runEnsure every binding exists at the top level and in the local environment where Wrangler requires non-inherited configuration.