You've been staring at the same 40 lines of code for two hours. You're convinced the problem is in the database query. You've rewritten it three times. You've Googled the same error message so many times that it's now in your browser autocomplete. You've blamed the ORM, the driver, the network, the moon.
The bug is in line 7. It's a missing await.
Sound familiar? Welcome to debugging — where your first instinct is almost always wrong, and the sooner you accept that, the faster you actually fix things.
The Curse of the Expert Guesser
Here's what happens when most developers hit a bug:
- They read the error message (briefly)
- They form a theory about the cause
- They go looking for evidence that confirms the theory
- They find something that looks like evidence
- They fix the wrong thing
- They are confused when it doesn't work
- They repeat steps 1–6 three more times
This is called confirmation bias, and it is absolutely devastating in debugging. Your brain is not trying to find the truth — it's trying to prove itself right. And it's annoyingly good at that.
The moment you think "I bet it's the cache," you will find seventeen things that look like cache problems. The cache is probably fine. The cache is almost always fine.
The Fix: Treat Debugging Like a Science Experiment
Good debugging is not guessing with confidence. It's forming a hypothesis and then actively trying to disprove it.
Ask yourself: "If I am wrong about this, what would that look like?"
If your theory is that the database query is slow, what does it look like if the query is actually fast? Check. Actually measure. Don't assume. The fastest way to find a bug is to ruthlessly eliminate what the bug is not.
This sounds obvious. Nobody does it.
Instead, most of us do this:
# Something is wrong. Let's add print statements everywhere.
print("here 1")
print("here 2")
print(data)
print("here 3 - still broken")
print("WHY")
Which is fine — but only if you're actually reading the output and updating your theory based on what you see, not just hunting for confirmation.
The Real Reason Debugging is Hard
It's not the complexity of the code. It's the distance between the symptom and the cause.
The error appears in the frontend. The bug is in the backend validation logic. The test fails in CI. The bug only exists when environment variables are loaded in a certain order. The app crashes in production. The bug is a timezone issue that only surfaces in UTC+2 on Tuesdays.
Most bugs are not where they appear. They are upstream. Something failed, something else caught it silently, something else passed bad data forward, and eventually something blew up three layers away from where the original sin happened.
So when you see an error, your first question shouldn't be "what's broken here?" It should be "what gave this code bad input?"
Trace backwards. Always trace backwards.
Things I've Learned the Embarrassing Way
Read the full error message. Not the first line. The whole thing. The part you need is usually at the bottom, and you've been ignoring it because you formed a theory at line one.
Rubber duck it early. The moment you start writing a Stack Overflow question and you have to actually describe what you tried, you will frequently solve your own problem before you hit Post. The rubber duck does not care how long you've been coding. It just wants you to explain it clearly. Explaining it clearly forces you to think clearly.
The last thing you changed broke it. I know you don't want to hear this. I know you were just "cleaning up." You broke it. Check git diff.
If it works on your machine and not in production, the environments are different. Not slightly. Fundamentally. Find the difference before you do anything else. Environment variables, versions, file paths, memory limits — something is different. Find it.
Sleep is a debugging tool. I don't know why this works. Your brain does something when you stop looking at it. You will wake up at 3 am and know exactly what's wrong. Happens to everyone.
The Bug That Wasn't a Bug (For Real This Time)
Once, I spent an entire afternoon convinced a third-party API was returning inconsistent data. I logged everything. I added retries. I considered switching providers. I drafted an angry support ticket.
The API was fine.
I was passing a parameter name with a capital letter instead of lowercase. The API silently ignored it and returned defaults every single time. Consistent. Predictable. Not a bug at all. Completely my fault.
The real lesson isn't "check your parameter names" (although yes, check your parameter names). The lesson is that the system was behaving exactly as designed. I was wrong about the contract. My understanding was the bug, not the code.
A lot of bugs are like this. The code is doing exactly what you told it to do. You told it to do the wrong thing.
One Practical Habit That Will Actually Help
When you've been stuck for more than 30 minutes, write down — physically or in a comment — exactly what you believe is happening and why. Not what you want to be happening. What you believe is actually happening right now.
Then look at what you wrote. Is each sentence something you measured, or something you assumed? The assumptions are where the bug lives.
Most bugs are not mysterious. They're just hiding inside something you were too confident about to check.
Go check it.