Debugging Checklist for Founders:The 5-Minute Fix Order

A debugging checklist: when something breaks, check things in this exact order: refresh the page, read the console, confirm you're logged in, confirm the app is actually running, confirm you saved your changes. Those five checks take five minutes and resolve 90% of issues. The order is the method — most founders debug by guessing randomly, which is why they stay stuck.

Debugging is a skill, not magic. Here's the full checklist, from the five-minute quick check to the nuclear option.

Debugging checklist, step 1: the 5-minute quick check (90% of issues)

1. Refresh the page. It clears temporary state and reloads your data. If a plain refresh doesn't help, do a hard refresh — hold Shift while refreshing — which also clears the cached files your browser may be serving from last week.
2. Open the console and look for red. The browser's developer console is where errors announce themselves. Red text is an error, and the message usually names the file and line. If it reads like hieroglyphics, how to read error messages decodes the patterns.
3. Are you logged in? Most features require authentication, and sessions expire quietly. Look for your user info in the header; when in doubt, log out and back in. An astonishing share of "broken" features is just an expired login.
4. Is the app actually running? If you're working locally, check the terminal — your development server should be printing logs. If it crashed or was never started, nothing will work, and no amount of code-staring will fix it.
5. Did you save the file? Unsaved changes don't run. Look for the dot next to the filename in your editor. Yes, this one catches everyone.

Most bugs are this simple: not logged in, forgot to save, server not running, typo, forgot to refresh. Start with the simple stuff first — it's not beneath you, it's statistics.

The 15-minute deep check

If the quick check didn't find it, go one layer down — still in order, still one thing at a time:

• Clear the browser cache. Old cached files can conflict with new code. A hard refresh usually does it.
• Open the Network tab. In the same developer tools, the Network tab shows every request your app makes. Refresh the page and look for red rows — failed requests — and read their status codes (table below).
• Did your database changes actually apply? If you recently changed the database structure, confirm the change ran — a missing table or column breaks everything that touches it. Check your database dashboard for the table you expect.
• Check your settings file. Apps read secrets and addresses from an environment file. Missing values, a wrong key, or extra spaces break everything — and after changing it, you must restart the app for it to notice.
• Suspect your most recent change. If it worked an hour ago, whatever you changed since is the prime suspect. Temporarily undo or comment out the newest change and see if the problem disappears.

What the Network tab is telling you

Those four rows turn the scariest tab in the browser into a triage nurse: they tell you whether the problem is your session, your address, or your code.

The bookThe Solopreneur RevolutionLuis Gonçalves on building a solopreneur business with AI while employed.Get the book →

The nuclear option

When nothing else works, there's the developer's version of "turn it off and on again": stop the app, delete the installed dependencies, reinstall them fresh, clear the browser cache, and restart. It sounds crude, but it reliably fixes corrupted installs, outdated dependencies, and the maddening category of "it works on my friend's computer but not mine."

Use it last, not first — because it fixes things without telling you what was wrong, and next time you'll be just as stuck.

The three rules that make the checklist work

Change one thing at a time. If you change five things and it starts working, you don't know what fixed it — which means you also don't know what broke it.

Test after each change. Don't pile up fixes. Make a change, check, move on.

Document what worked. The same bugs recur. A notes file of "symptom → fix" becomes your fastest debugging tool within a month.

And when the checklist runs dry: escalate deliberately, not desperately. Hand the error to your AI assistant using the AI debugging prompts, or write a proper bug report using how to ask for technical help. By then you can answer what you were doing, what you expected, what happened, and what you've tried — which is exactly what the checklist just made you gather.

12 weeksYour corporate career was never the planApply to the Solopreneur Accelerator.Apply now →

Frequently asked questions

What should I check first when my app breaks?

Refresh the page, then read the console. Those two steps take under a minute and resolve a huge share of problems on their own. Then confirm you're logged in, the app is running, and your changes are saved. Only after those five should you start reading code.

Why does debugging in a fixed order matter?

Because random guessing changes several things at once, so you never learn what was actually wrong. A fixed order tests the most likely, cheapest-to-check causes first and eliminates them one by one — which is faster on average and teaches you your system's failure patterns as a bonus.

My changes aren't showing up — what's wrong?

In order of likelihood: you didn't save the file, the app isn't running, your browser is showing a cached version (hard refresh), or you're editing a different file than the one the app is using. All four are two-minute checks, and together they cover nearly every case.

When should I stop debugging and ask for help?

After the quick check and the deep check — roughly 20 minutes of systematic work. By then you can state what you were doing, what you expected, what happened, the exact error, and what you've tried. That's everything a good help request needs, whether you're asking an AI or a human.