Try the targeted fix first. If it does not unstick you, the bottom of each section explains what to check next.
Dev server lock / port already in use
Symptom: `npx next dev` exits with EADDRINUSE on port 3000, or hangs without serving.
- Find the process: `lsof -i :3000` (mac/linux) or `netstat -ano | findstr :3000` (Windows).
- Kill the PID it returns.
- Run `npx next dev` again. If you actually want to keep both, run on a free port: `npx next dev -p 4317`.
Migration not run
Symptom: pages 500 with errors like "relation project_previews does not exist".
Apply migrations against the deployment's Supabase project:
- Confirm `supabase/migrations/` contains the file the error references.
- Run `supabase db push`, or paste the migration into the Supabase SQL editor.
- Reload the page.
Preview link not loading
Symptom: /preview/<token> returns 404 even though you just enabled it.
- Check the Deploy mode toggle is actually on for that project.
- Make sure you copied the latest token — rotating invalidates old URLs immediately.
- Verify the migration adding `project_previews` ran in your environment.
- Hit the URL with `?t=1` to bust browser cache.
AI request returns 401
Symptom: chat in the project page fails; the network panel shows POST /api/ai returning 401 with `{"error":"Unauthorized"}`.
You are not authenticated. Sign in again. The project page does not auto-redirect to /login when the session expires; reload the page after logging in.
Typecheck issues
Symptom: `npx tsc --noEmit` complains about types you did not change.
- Confirm you are on the right branch.
- Delete `.next/` and `node_modules/.cache/`, then re-run.
- If the error references a Supabase types file, run `supabase gen types` to regenerate.
Browser still showing old design
After a theme refresh or design refresh deploy, you may see the old CSS for a moment. The fix:
- Hard reload (Shift + reload on most browsers).
- Clear site data for the 6cript origin if you are deeply stuck.
- In dev, restart the dev server to flush its CSS cache.