← Back
How I Think While Debugging: A Framework for Chaos

How I Think While Debugging: A Framework for Chaos

Writing code is the easy part. It’s translating a known set of requirements into syntax. Debugging, on the other hand, is the actual job. It is an exercise in applied epistemology: how do you know what you think you know?

When a difficult bug hits, the natural instinct is to start tweaking things. Change a let to a const. Add a console.log. Restart the server. Try it again. This is called "shotgun debugging," and it scales terribly.

Over time, I've had to replace panic with a systematic approach. Here is the mental framework I use when the console is bleeding red and the root cause is nowhere to be found.

1. Stop Guessing, Start Proving

The single biggest mistake developers make is changing code before they understand why it's broken.

If you don't know why a bug is happening, any fix you apply is just a coincidence. You might make the symptom disappear, but the underlying rot remains. Instead of guessing, operate like a scientist: form a hypothesis, devise a test to prove or disprove it, and observe the result.

"I think the user object is undefined because the API call hasn't resolved."
Test: console.log(user, isLoading) right before the crash.
Result: Prove it. Only then do you change the code to handle the loading state.

2. Halve the Search Space (Binary Search for Bugs)

When you're dealing with a large system, the bug could be anywhere. Is it a CSS issue? A React state problem? A bad API payload? A database constraint?

Use binary search. Cut the system in half and figure out which half the bug is in.

  1. Check the network tab: Did the API return the right data but the UI didn't render it? (The bug is in the frontend). Or did the API return a 500? (The bug is in the backend).
  2. If it's the backend: Check the logs right before the database query. Are the parameters correct? If yes, the query is bad. If no, the controller logic is bad.

Keep halving the search space until you isolate the exact function that is lying to you.

3. Read the Error (Actually Read It)

This sounds patronizing, but I have caught myself doing it, and I see junior engineers do it all the time: looking at an error instead of reading it.

Stack traces are intimidating walls of text. Your brain wants to glaze over them and jump back to the code. Resist that urge.

  1. What is the explicit error message? (TypeError: Cannot read properties of undefined (reading 'map'))
  2. What file did it originate from?
  3. What line number?

The computer is usually screaming the exact cause of the pain. You just have to listen to its abrasive tone.

4. Trust Nothing (Check Your Assumptions)

Bugs hide in the gap between what you think the code is doing and what it is actually doing. When you are stuck for more than 30 minutes, it is almost always because one of your foundational assumptions is wrong.

  • "The ID is definitely a number." (It's a string).
  • "This function only runs once." (A useEffect dependency array is missing, so it's running infinitely).
  • "The database constraint prevents duplicates." (The constraint was added to a different environment).

When I'm completely blocked, I start physically writing down my assumptions on a piece of paper, and then I use console.log or a debugger to prove each one is true in reality, not just in my head.

5. Walk Away

Your brain has two modes: focused mode and diffuse mode.

Focused mode is what you use when you're heavily tracking the execution flow of a complex function. It's powerful, but it gets tunnel vision easily.
Diffuse mode is the background processing that happens when you take a shower, make coffee, or walk the dog. It connects disparate ideas.

If you have stared at a bug for 45 minutes and haven't made progress, your focused mode has failed. You are likely stuck in a loop of trying the same three wrong ideas. Get up. Walk away. Let your diffuse mode look at the problem from a different angle. The answer often arrives the moment you stop actively looking for it.

The Bottom Line

Debugging is not a talent you are born with; it is an algorithm you run in your head.

The next time you face a wall of red text, take a breath. Don't touch the keyboard. Read the error. Form a hypothesis. Cut the search space in half.

The bug is just code doing exactly what you told it to do. You just need to figure out what you actually said.