Debugging isn’t about finding bugs—it’s about understanding systems deeply enough that bugs become obvious. After fifteen years of tracking down issues in production systems, I’ve developed a mental framework that works.

The Wrong Way to Debug

Let me start with what doesn’t work, because I did all of these things for years.

Random changes. “Maybe if I add a null check here? What if I clear the cache? Let me just try restarting the service.” This is not debugging; it’s superstition. You might stumble onto a fix, but you won’t understand why it worked, which means you won’t learn anything, and the bug will probably come back.

Assuming you know where the problem is. You’ve seen this code a hundred times. You know it works. The bug must be somewhere else. Three hours later, you discover the bug was in the code you “knew” worked. Our intuitions are useful, but they’re not reliable. Verify everything.

Fixing the symptom instead of the cause. The application crashes when processing large files? Just add a size limit! Problem solved, right? No. You’ve added a band-aid. The underlying issue—maybe a memory leak, maybe an inefficient algorithm—is still there, waiting to manifest in a different way.

Debugging in production. Adding print statements to live code. Watching logs in real-time. Trying changes against real data. Sometimes this is unavoidable, but it should be a last resort, not a first instinct. Production is where bugs hurt users. Debug somewhere else when you can.

Start by Reproducing

Before you do anything else, reproduce the bug. Reliably. Every time.

This sounds obvious, but I’ve watched engineers spend hours debugging issues they couldn’t actually reproduce. They’d make a change, try it once, see that the bug didn’t happen that time, and declare victory. Then the bug would reappear and they’d start over.

If you can’t reproduce a bug, you have two problems: the original bug, and the fact that you don’t understand the conditions that trigger it. Solve the second problem first.

Sometimes reproduction is easy. The bug happens every time you click a certain button. Great. More often, it’s intermittent: happens under load, happens with certain data, happens on Tuesdays for reasons nobody understands. Your job is to narrow down the conditions until you can make it happen on demand.

This is where careful observation pays off. What do the failing cases have in common? What’s different about the times it works? Gather data before forming hypotheses.

Question Your Assumptions

Most bugs exist because something you believed was true turned out to be false. The fastest path to finding a bug is identifying which assumption is wrong.

I once spent a full day debugging a payment processing issue. Transactions were being duplicated under certain conditions. I traced through the code, checked the database, examined the queue—everything looked correct. Finally, out of desperation, I checked the clock synchronization between servers. They were off by several seconds, just enough to cause a race condition in our idempotency logic.

I had assumed the clocks were synchronized. They weren’t.

Make your assumptions explicit. Write them down if you need to. Then verify each one. Don’t trust documentation—check the actual behavior. Don’t trust your memory of what the code does—read the code. Don’t trust that the environment is configured correctly—check it.

The bug is hiding in the gap between what you think is true and what’s actually true. Find the gap.

Isolate the Problem

A complex system has thousands of potential failure points. Your job is to narrow that down until you’ve found the one that matters.

Binary search is your friend. If a bug appears somewhere in a chain of 10 operations, test operation 5. If the bug is present, it’s in operations 1-5. If not, it’s in 6-10. Repeat until you’ve found the exact point of failure. This is faster than testing linearly, especially in large systems.

Remove components. Can you reproduce the bug without the cache? Without the network call? Without the async processing? Each component you can eliminate is one less place the bug could be hiding. Sometimes you’ll discover the bug only manifests when certain components interact.

Minimize the reproduction case. If the bug happens with a 10,000-line input file, can you trigger it with 100 lines? With 10? The smaller your reproduction case, the easier it is to see what’s happening.

Use git bisect. If the bug is a regression—it used to work and now it doesn’t—let git bisect do the work. It will binary search through your commit history to find exactly which commit introduced the problem. I’ve tracked down bugs in seconds that would have taken hours to find manually.

Read the Error Message

I mean really read it. Not glance at it. Not just note the error type. Read every word. Read the stack trace. Read the context.

Error messages exist because some programmer thought this information would be useful for debugging. They were right. The message often tells you exactly what went wrong, if you’re willing to pay attention.

I can’t count the number of times I’ve asked a junior developer “what does the error message say?” and watched them actually read it for the first time. “Oh. It says the file doesn’t exist.” Well then.

Some error messages are genuinely unhelpful. “An error occurred.” Thanks for nothing. But even these tell you something—they tell you that the error handling in that part of the code is poor, which might itself be useful information.

Form Hypotheses, Then Test Them

Once you’ve gathered information, form a hypothesis about what’s causing the bug. Be specific. “Something is wrong with the database” is not a hypothesis. “The query is returning stale data because the cache TTL is too long” is a hypothesis.

Then test it. Not by trying to fix it—by trying to prove it wrong. What would you expect to see if your hypothesis were true? Go look for that evidence. If you can’t find it, your hypothesis is probably wrong. Form a new one.

This is the scientific method applied to code. It works for the same reasons: it protects you from confirmation bias and forces you to engage with actual evidence instead of intuitions.

Use the Right Tools

Print statements are fine for simple bugs. For complex issues, you need better tools.

Debuggers let you stop execution, inspect state, and step through code line by line. If you’re not comfortable with your debugger, get comfortable. The time investment pays off many times over.

Logging gives you visibility into systems you can’t attach a debugger to. But logging requires forethought—the logs you need for debugging have to be added before the bug happens. Log generously, especially at system boundaries.

Profilers help when the bug is performance-related. Is that function slow because it’s called once and takes forever, or because it’s called a million times and they add up? A profiler will tell you.

Distributed tracing is essential in microservices architectures. When a request touches ten different services, you need to see the whole journey to understand where it went wrong.

Time-travel debuggers and record-replay systems let you capture a failure and examine it later. These are particularly valuable for intermittent bugs or race conditions.

Know When to Stop

Some bugs aren’t worth fixing. The time you’d spend tracking down a rare edge case might be better spent on features that help more users. This is a judgment call, but it’s one you should make consciously.

Similarly, know when to ask for help. Fresh eyes often see what you’ve been missing. There’s no prize for suffering alone. If you’ve been stuck for hours, talk to someone.

And know when to take a break. Your brain is not a machine. When you’re tired and frustrated, you make mistakes. You overlook the obvious. You go in circles. Sometimes the best debugging technique is to get a good night’s sleep and look again in the morning. The bug will still be there, but you’ll be sharper.

The Meta-Skill

The best debuggers I know share a common trait: curiosity. They genuinely want to understand why things happen. Not just fix the symptom and move on, but really comprehend the underlying mechanism.

This curiosity transforms debugging from a chore into a puzzle. Every bug is an opportunity to learn something about how systems behave. Over time, these lessons accumulate into intuition—not the unreliable intuition of assumptions, but the earned intuition of someone who has seen many failure modes and understands how software actually breaks.

Bugs are inevitable. Getting good at finding them is a career-long investment that pays dividends on every project you touch.