Troubleshooting

Symptom	Probable cause	What to check	Fix direction
/api/auth/session returns HTML or client JSON parse errors	Gateway worker route missing or wrong host/env	wrangler.gateway.toml routes for current hostname; whether request hits static bucket only	Add/fix routes; redeploy gateway
/portal/outgoing-mail loops to login	No Access token, verify URL wrong, or path not protected consistently	Cloudflare Access for hostname; AUTH_WORKER_VERIFY_URL; PROTECTED_PATH_PREFIXES and gateway routes	Align Access + gateway config; fix verify URL for env
Header stays Login after you expect auth	Session not success: true, layout script error, or missing JWT/cookie	Browser network tab for /api/auth/session; console errors; Access cookie presence	Fix worker verify; fix CSP/connect; fix Access app scope
Outgoing mail fails after auth	Wrong PUBLIC_OUTGOING_MAIL_WORKER_URL, CSP/CORS, or Resend/upstream	_headers connect-src / form-action; worker logs; mail worker Access	Correct env URL; relax CSP only as needed; check mail worker
Images skip optimization	Route pattern omits extension or optimizer disabled	wrangler.image.toml routes; ENABLE_IMAGE_RESIZING; URL missing width query	Adjust routes; enable flag; use supported query contract
Entire site shows maintenance	Maintenance flag on	PUBLIC_MAINTENANCE_MODE in .env / build env	Set to false and rebuild/redeploy

Turnstile

• Widget errors: confirm PUBLIC_TURNSTILE_SITEKEY matches the sitekey for the environment; domain allowlist in Cloudflare Turnstile.
• Server validation failures: TURNSTILE_SECRET_KEY must match the widget’s sitekey account; check for staging vs production mix-ups.

CSP

Symptoms: blocked fetch to session, mail worker, or analytics. Inspect browser console for CSP violation messages. Compare requested origin to Content-Security-Policy in public/_headers (connect-src, form-action, script-src, frame-src for Turnstile).

Missing envs

• Build-time: Astro PUBLIC_* undefined → features silently disabled or broken. Check .env and deployment env injection.
• Worker: Missing AUTH_WORKER_VERIFY_URL falls back to code default—may be wrong for staging; always verify Wrangler [vars].