Troubleshooting

You see	Cause and fix
502 (Bad Gateway) on /api/... at localhost:5173	Vite is up but Django on port 8000 isn't, usually while npm run dev is still starting or the database container is restarting. Check the api lines in the terminal, make sure Docker Desktop is running, then restart npm run dev. curl http://127.0.0.1:8000/healthz should answer "status": "ok".
No "Continue with Google" button	GOOGLE_CLIENT_ID or GOOGLE_CLIENT_SECRET is empty, or Django isn't running.
Google says redirect_uri_mismatch	Add APP_URL + /sso/google/callback/ under Authorized redirect URIs. See Configuration.
No reCAPTCHA visible	Normal: v3 is invisible. The notice under the form confirms it is on.
ERROR for site owner: Invalid domain in the checkbox	Add the domain you're on (for example localhost) to the reCAPTCHA key.
No sign-up code email	Without Resend the code is printed in the terminal; with Resend, check its logs.
Failed to parse environment file	A value in .env with spaces or < > isn't quoted.
The app won't start: missing FIELD_ENCRYPTION_KEYS	Generate one (see Developer Setup) and set it.
/status/ says "No heartbeat yet"	The worker or Beat isn't running, or started before the last settings change. Restart npm run dev and wait about a minute.
Blank page, "Invalid hook call"	Delete frontend/node_modules/.vite and restart.
Template change doesn't show	Public pages are cached; touch a .py file or add a query string.
Tests fail at random with database errors	Two test runs at once share the test database. Run one at a time.
Attack simulation rate-limit checks fail on Windows	Use 127.0.0.1, not localhost (IPv6 lookup adds about 2 s per request).

Still stuck? Open an issue with the command you ran and the full error.