Stuck on One Bug for Days: A Systematic Debugging Method
- Author
- Vishal Maurya
- Published on
- Reading time
- 4 min read
Overview
Two days into the same bug, you have tried a dozen changes, you no longer remember which ones helped, and the code looks worse than when you started. Long debugging sessions rarely fail from lack of intelligence. They fail because the process drifted into guessing.
This is a method to get back on track.
1. Stop and Reset
Revert speculative changes so you are working from a known state. Commit or stash anything you want to keep. Then write down, in a few lines:
Expected behavior:
Actual behavior:
How to trigger it:
What I know for sure:
What I have assumed but not verified:
What I have already tried and the result:
The "assumed but not verified" list is often where the bug hides. A fix that depends on an unchecked assumption is a guess.
2. Reproduce Reliably
You cannot debug what you cannot trigger on demand. Aim for a single command or script that shows the failure. If it is intermittent, loop it, add parallelism, or fix inputs and clocks until it fails predictably. A reliable reproduction is worth more time than another theory.
3. Minimize
Strip the problem down. Remove code, inputs, configuration, and dependencies until the smallest case that still fails remains. Each removal that does not change the failure shows something is irrelevant; the removal that makes it disappear points at the cause.
A minimal example is also what you will need if you ask someone else for help.
4. Form and Test Hypotheses
Write a hypothesis as a prediction that can be wrong: "If the cache returns stale data, then clearing it should fix the failure and the log will show a hit." Then run the cheapest test that could disprove it.
Hypothesis: the timeout is caused by the connection pool being exhausted
Prediction: pool size increased -> failure disappears; active connections hit the max in metrics
Test: check pool metrics at failure time, then raise the pool size in a test run
Result: ...
Record results, including negative ones. Change one thing per experiment.
5. Bisect
When something used to work, bisect to find the change that broke it. With git, let the tool do the search:
git bisect start
git bisect bad # current commit fails
git bisect good v1.4.0 # a known good commit or tag
# git checks out a midpoint; test it, then mark it:
git bisect good # or: git bisect bad
# or automate with a script that exits 0 for good and non-zero for bad:
git bisect run ./scripts/repro.sh
git bisect reset
You can bisect other dimensions too: the input data, configuration values, or the order of lines in a function. Halving the search space beats scanning it.
6. Explain It Aloud
Rubber-duck debugging works because describing the problem in order forces you to state your assumptions. Explain to a colleague, an object on your desk, or a written note: what the code is supposed to do, line by line, and where reality diverges. Many bugs surface halfway through the explanation.
Also change the context. Take a walk, sleep on it, or work on something else for an hour. Fatigue narrows thinking.
7. Know When to Ask, and How
Set a time limit before you start, such as a couple of hours of focused attempts after which you ask. Asking is not failure; it is cheaper than days of solo struggle. A good question lets someone help without a call:
Title: Short description of the symptom
What I am trying to do:
What happens instead (exact error text):
Minimal reproduction (code or steps):
Environment (versions, OS, config):
What I tried and what each attempt showed:
What I suspect and why:
Include logs as text, not screenshots, and remove secrets. Keep the question to one problem, and report back the solution afterward so others benefit.
Conclusion
When you are stuck, return to process: reset, reproduce, minimize, test explicit hypotheses, bisect, explain it, and ask with a clear write-up. The discipline of recording what you know and what you assume does most of the work.
If you are blocked on a stubborn bug in a Python, Django, or backend system, I can help investigate. Contact me.