Troubleshooting

Common issues and how to fix them.

Problem	Cause	Fix
Invalid username or password	ALLOWED_ORIGINS mismatch (CORS block)	Set `ALLOWED_ORIGINS` to exactly match the URL in your browser — not `localhost` if you're using the server IP
Backend crashes on start	Extra fields in `.env`	Add `"extra": "ignore"` to `model_config` in `config.py`
Frontend can't reach backend	Wrong `NEXT_PUBLIC_API_URL`	Update `.env.local` and rebuild with `npm run build`
venv not created on deploy	Missing `python3-venv`	`sudo apt install python3-venv`
systemctl permission denied	No passwordless sudo rule	Add `NOPASSWD: /bin/systemctl` to `/etc/sudoers`
TS build error: unknown[]	Missing type cast on API response	Cast with `data as User[]`
useSearchParams Suspense error	Next.js requires Suspense boundary	Wrap component using `useSearchParams()` in `<Suspense>`

Useful Debug Commands

# View backend logs
sudo journalctl -u pycon-backend -f

# Test login directly
curl -s -X POST http://YOUR_IP:8000/api/auth/login \
  -d "username=admin&password=yourpassword" \
  -H "Content-Type: application/x-www-form-urlencoded"

# Health check
curl -s http://YOUR_IP:8000/api/health

# Check service status
sudo systemctl status pycon-backend pycon-frontend