Debugging workflow

When you don’t know where to start — the systematic approach.

The five questions

1. What did I expect to happen?

   Be specific. “I expected the form to submit and the toast to appear” is good. “It should work” is not.

2. What actually happened?

   Specifically. Error message? Silent failure? Wrong data?

3. When did it last work?

   Five minutes ago? Yesterday? After a specific change? Use version history to compare.

4. What changed since?

   Often the answer is in the diff between the last known-good revision and now.

5. Can I reproduce it reliably?

   If yes, you’re 80% to a fix. If no, focus on logging and capturing state when it next happens.

Where to look

Symptom	Look in
White screen	Browser console (uncaught error)
Action fails silently	Convex function logs
Wrong data displayed	Run the query directly in vly’s data explorer
Slow	Performance profiler (Chrome DevTools)
Type error	Build log
Webhook not firing	Provider’s webhook log + Convex HTTP action log

The bisect

If something broke “sometime today” and you don’t know when:

1. Open version history.
2. Pick the midpoint revision; preview it.
3. Bug present? Bisect to the older half. Bug absent? Bisect to the newer half.
4. Repeat until you find the offending revision.

5–10 minutes max for hundreds of revisions. Faster than any other method.

Asking for help

When you do reach out (Discord, support), include:

• What you expected vs. got.
• Steps to reproduce.
• Project ID and revision ID.
• Browser console errors / Convex log excerpts.

Vague help requests get vague help. Specific ones get specific.

Related

Common errors

Patterns.

Version history

The bisect target.

Contacting support

Channels and what to include.