How to Debug Code Systematically When You're Stuck
A repeatable debugging method for when staring at the code isn't working — reproduce, read the error, form hypotheses, bisect with git, shrink to a minimal example and verify the fix — with techniques for "works on my machine" bugs.
By Software Side Hustles Editorial Team · Published · Updated · 5 min read
Quick answer: stop changing code at random. (1) Reproduce the bug reliably. (2) Read the full error and stack trace. (3) Write down what you expect versus what happens. (4) Form one hypothesis and test it with a breakpoint, log or assertion. (5) Narrow the search space by halves — in the code, the input, or the commit history with git bisect. (6) Fix the root cause, and add a test that would have caught it.
Step 1: reproduce it reliably
You cannot confirm a fix for a bug you cannot trigger. Write down the exact steps, input, environment and expected result. If it happens "sometimes", look for what varies: timing, data, user, time zone, concurrency, cache state, order of tests.
A reproduction you can run in one command — a failing test, a curl request, a script — is worth more than any amount of reasoning. It also tells you, unambiguously, when you have fixed it.
Step 2: read the error properly
It sounds obvious, yet many debugging sessions start by skimming past the one line that explains the problem. Read the exception type, the message and the stack trace from your own code's first frame. See how to read a stack trace. Then search the exact message — quoted, without your file names — because someone has very likely hit it before.
If there is no error — the output is just wrong — find the first point where the program's state differs from what you expect. That is the bug's real location, which may be far from where it becomes visible.
Step 3: state your assumptions
Write them down: "user is loaded before this runs", "the list is sorted", "this config value is 30 seconds, not 30 milliseconds". Bugs live in the gap between what you assume and what is true. Rubber-duck debugging — explaining the code line by line to someone (or something) else — works because it forces you to state assumptions you were skipping over.
Step 4: test one hypothesis at a time
For each hypothesis, decide what observation would confirm or refute it before you look:
- Print/log debugging is fast, works everywhere (including production logs) and leaves a record. Log values and types:
print(repr(x), type(x))reveals'5'versus5and trailing whitespace. - A debugger (VS Code, IntelliJ, Chrome DevTools,
pdb/breakpoint()) lets you pause, inspect every variable and step through the logic. Conditional breakpoints (i == 999) and "break on exception" are especially powerful. - Assertions turn assumptions into checks:
assert items == sorted(items), items[:10].
Change one thing at a time. If you change three things and the bug disappears, you do not know which change fixed it — or whether one of them introduced a new problem.
Step 5: divide and conquer
When you do not know where the bug is, halve the search space repeatedly.
In the code: check the state at the midpoint of the process. Correct there? The bug is later. Wrong? Earlier.
In the input: if a 10,000-line file breaks the parser, try the first 5,000 lines, then 2,500, until you find the smallest input that fails.
In history, with git bisect: when something used to work, Git can find the exact commit that broke it in a logarithmic number of steps:
git bisect startgit bisect bad # the current commit is brokengit bisect good v2.3.0 # this tag was fine# Git checks out a commit halfway between; test it, then:git bisect good # or: git bisect bad# ...repeat until Git names the first bad commitgit bisect resetWith an automated test you can let Git do all the work: git bisect run npm test. A range of 1,000 commits takes about ten steps.
Step 6: build a minimal reproducible example
Remove everything not needed to trigger the bug: unrelated code, dependencies, data, configuration. Often you find the bug during this process, because removing the "irrelevant" part suddenly makes it go away. If you do not, you now have exactly what a colleague, an issue tracker or a forum needs to help you — a short, complete, runnable example with the expected and actual result.
Step 7: fix the cause, not the symptom
Ask "why" until you reach something you can fix properly. The page crashes because user is undefined; user is undefined because the request failed; the request failed because the token expired; the token expired because refresh is not implemented. Adding user?.name fixes the crash and hides the real bug.
Then verify:
- Run the original reproduction — it should now pass.
- Add an automated test that fails without your fix. See how to write good unit tests.
- Look for the same pattern elsewhere — bugs come in families.
"Works on my machine": comparing environments
When code behaves differently between environments, list the differences and eliminate them one by one:
- Versions: language runtime, dependencies (is the lockfile committed and used?), database, OS.
- Configuration: environment variables, feature flags, secrets, locale and time zone.
- Data: production has nulls, long strings, unicode and volumes your test data does not.
- State: caches, stale builds, leftover files, a database migration that has not run.
- Timing: slower networks and more concurrency expose race conditions.
Containers (Docker) and pinned dependencies shrink this list dramatically.
When to step away
If you have been stuck for an hour without new information, stop. Take a walk, explain the problem in writing to someone, or sleep on it. Fresh eyes are a genuine debugging tool — many bugs are found within minutes of coming back. Asking for help early, with a clear reproduction and what you have already ruled out, is a strength, not a weakness.
Frequently asked questions
Debugger or print statements?
Both. Print statements are quick and work in any environment; a debugger is better for exploring unfamiliar code and complex state. Use whichever gets you new information fastest.
How do I debug a problem that only happens in production?
Improve observability: structured logs with request IDs, error tracking with stack traces, metrics and traces. Try to reproduce with production-like data in staging. Feature flags let you test a fix on a subset of traffic.
How do I get better at debugging?
Practise deliberately: read other people's code, review pull requests, and predict what code will do before running it. Exercises that ask you to find the bug in someone else's solution are particularly effective.
Where this skill pays off
Systematic debugging is the single most transferable engineering skill — and it is exactly what AI training platforms pay developers to apply when they judge whether a model's fix is right. Try finding the bugs in our free code review lab, or book one-to-one tutoring to sharpen your code-reading and debugging under guidance.