Troubleshooting & Logs
Quick pointers to the logs and first-fix steps for Cursor, GitHub, Supabase, and Vercel.
Troubleshooting & Logs
When something breaks, go straight to the right log, grab the error, and decide the next action.
Keep this page open while you build. Fast feedback beats frantic guessing—let the logs guide the fix.
Cursor IDE
Where to look: Cmd/Ctrl + L opens the chat panel history. Cmd/Ctrl + `` opens the integrated terminal.
What to look for: Last failed command, model response errors, stack traces in the terminal.
First fix steps:
- Re-run the command with
--verboseif available (e.g.,npm run dev -- --verbose) - Highlight the error message and ask Cursor: "Explain this stack trace and propose a fix"
- If Cursor keeps guessing, paste the relevant file section and restate the requirement plainly
GitHub
Where to look: Repo → Pull Requests → select PR → Checks tab for Actions logs.
What to look for: Red ❌ steps, especially build, lint, or deploy.
First fix steps:
- Click the failing job → View raw logs to copy the exact error
- If lint/test failure, reproduce locally with the same command shown in the log
- For permission or secret issues, confirm the GitHub → Vercel/Supabase integration scopes
- Restart only after you understand the failure—otherwise you'll burn time waiting
Vercel
Where to look: Vercel dashboard → your project → Deployments → select the failing build → Logs.
What to look for: Build step errors (dependency install, Next.js build) or runtime errors after deploy.
First fix steps:
- Match the failing step with the corresponding local command (
pnpm install,pnpm build, etc.) - Check Environment Variables tab—missing env vars are the #1 production issue
- If runtime errors appear post-deploy, run
vercel logs <deployment-url>or open the deployment URL with browser dev tools
Supabase
Where to look: Supabase dashboard → project → Logs (top nav) or Table Editor / SQL for schema errors.
What to look for: API errors (Auth, Functions), Postgres errors, rate limit warnings.
First fix steps:
- For migration failures, run
supabase db pushlocally and watch the terminal output - Database errors often reference a specific table/column—jump to that migration file and verify schema
- Auth/function issues: open Authentication → Providers or Edge Functions → Logs for more context
- If you broke local dev, reset with
supabase db reset(warn team before wiping data)
General Debugging Process
When you're stuck:
- Capture the exact error message and where it appeared
- Note what changed right before the failure
- Share both in Cursor or with your team
- Propose one hypothesis and one experiment to test it
Don't guess randomly. Form a hypothesis, test it, and iterate.
Common Issues Quick Reference
| Symptom | Likely Cause | Fix |
| "Unauthorized" or 401 errors | Missing env vars or RLS blocking | Check env vars; add RLS policies or disable temporarily |
| Build fails on Vercel but works locally | Missing env vars on Vercel | Add all NEXT_PUBLIC_* vars in Vercel dashboard |
| Supabase query returns empty | RLS enabled without policies | Add allow select policy or disable RLS for testing |
| Git push rejected | Remote has changes you don't | Run git pull first, resolve conflicts |
| "Module not found" errors | Missing dependency | Run npm install or pnpm install |
Still stuck? Check the CLI Services page for command references.
Ready to continue building? Return to Build with AI Flow.