SoftwareSideHustles
Debugging

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' versus 5 and 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:

bash
git bisect start
git bisect bad # the current commit is broken
git 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 commit
git bisect reset

With 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:

  1. Run the original reproduction — it should now pass.
  2. Add an automated test that fails without your fix. See how to write good unit tests.
  3. 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.

Cookies on this site

We use essential cookies to run the questionnaire, practice labs and sign-in. With your permission we'd also like to use analytics to understand which pages help people, and advertising cookies to measure our Google Ads. Rejecting never limits any feature. Cookie policy