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:

  1. Re-run the command with --verbose if available (e.g., npm run dev -- --verbose)
  2. Highlight the error message and ask Cursor: "Explain this stack trace and propose a fix"
  3. 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:

  1. Click the failing job → View raw logs to copy the exact error
  2. If lint/test failure, reproduce locally with the same command shown in the log
  3. For permission or secret issues, confirm the GitHub → Vercel/Supabase integration scopes
  4. 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:

  1. Match the failing step with the corresponding local command (pnpm install, pnpm build, etc.)
  2. Check Environment Variables tab—missing env vars are the #1 production issue
  3. 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:

  1. For migration failures, run supabase db push locally and watch the terminal output
  2. Database errors often reference a specific table/column—jump to that migration file and verify schema
  3. Auth/function issues: open Authentication → Providers or Edge Functions → Logs for more context
  4. If you broke local dev, reset with supabase db reset (warn team before wiping data)

General Debugging Process

When you're stuck:

  1. Capture the exact error message and where it appeared
  2. Note what changed right before the failure
  3. Share both in Cursor or with your team
  4. Propose one hypothesis and one experiment to test it

Don't guess randomly. Form a hypothesis, test it, and iterate.


Common Issues Quick Reference

SymptomLikely CauseFix
"Unauthorized" or 401 errorsMissing env vars or RLS blockingCheck env vars; add RLS policies or disable temporarily
Build fails on Vercel but works locallyMissing env vars on VercelAdd all NEXT_PUBLIC_* vars in Vercel dashboard
Supabase query returns emptyRLS enabled without policiesAdd allow select policy or disable RLS for testing
Git push rejectedRemote has changes you don'tRun git pull first, resolve conflicts
"Module not found" errorsMissing dependencyRun 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.