Every developer eventually runs into a bug that seems to make no sense.
The page is blank, even though the component looks fine. A function works with one input and fails with another. An error appears far from the code that caused it. The first instinct is often to change something—anything—and see if the problem goes away.
That instinct is understandable, but random edits can make a small bug harder to find. A more reliable approach is to slow down, gather evidence, and narrow the problem one step at a time.
Here’s a practical debugging process you can use whether you’re working on a small script, a website, or an unfamiliar codebase.
1. Describe the problem precisely
Start by replacing “it doesn’t work” with a specific description.
Ask yourself:- What did I expect to happen?
- What happened instead?
- What steps reproduce it?
- Does it happen every time, or only sometimes?
- Did it start after a particular change? For example, “the form is broken” is hard to investigate. This is more useful:
When I submit the sign-up form with a valid email and an empty password, it shows a loading indicator but never displays a validation message.
A clear description gives you something you can test. It also prevents you from chasing unrelated issues.
2. Reproduce the issue consistently
Before changing code, try to make the bug happen reliably. Record the steps and inputs that trigger it.
If the problem is inconsistent, look for details that vary:- The order in which actions happen
- The data being used
- The browser or device
- Network availability
- Whether the app was freshly loaded
- Whether an earlier action changed the app’s state A bug that happens “sometimes” may still follow a pattern. Reproducing it turns that pattern into evidence.
If you can’t reproduce the issue, avoid making speculative changes. First gather more information, such as logs, error reports, or a record of the steps that led to it.
3. Read the error message carefully
Error messages are not always written in friendly language, but they often tell you where to begin.
Look for:- The error type
- The file and line number
- The function where it occurred
- The values or operation involved
- The first line in the stack trace that belongs to your code The last line of a stack trace may show where the error surfaced, not necessarily where it began. Read upward and follow the path through your own code.
Search for the exact error text if you need help understanding it. But treat search results as clues, not automatic fixes. A similar error can have a different cause in your project.
4. Trace the data, not just the screen
Many bugs are caused by data being different from what the code expects.
Suppose a function expects a user object with an email property. The problem might be that the value is null, the property has a different name, or the data hasn’t loaded yet.
Follow the value through the steps where it changes:- Where does the data come from?
- What shape does it have at that point?
- Which functions transform it?
- Where is it used?
- Does it still match what the next step expects?
Logging a value can help, but log the relevant context too. Instead of printing only
undefined, inspect the object and the code path that produced it.
Be careful not to log passwords, access tokens, personal data, or other sensitive information.
5. Find the smallest failing case
Complex inputs can hide the cause. Try reducing the problem to the simplest case that still fails.
If a function processes a long list, test it with one item. If a form has many fields, test only the field that seems related. If a page has several components, temporarily isolate the one involved.
The goal is to remove details that don’t affect the bug. Once you have a small failing example, it becomes easier to understand and test.
This is also useful when asking someone else for help. A short example that reproduces the problem is usually more helpful than a large project with no clear starting point.
6. Change one thing at a time
When you make several changes at once, it becomes difficult to know which one mattered.
Instead, form a small hypothesis:
I think this value is missing because the request hasn’t completed before the component renders.
Then make one targeted change or add one observation to test that idea. If the result doesn’t support your hypothesis, undo or reconsider the change before moving on.
This makes debugging a process of learning, rather than trial and error.
7. Use breakpoints when logs aren’t enough
Logs show selected moments. A debugger lets you pause the program and inspect what is happening step by step.
Breakpoints are useful when you need to check:- Which branch of a conditional runs
- What a variable contains before and after a function call
- How many times a loop executes
- Whether a callback is reached
- Where execution stops or takes an unexpected path Step through the code slowly and compare what you observe with what you expected. Avoid inspecting every variable in the application; focus on the values connected to your current hypothesis.
8. Check recent changes
If the issue began recently, review what changed around that time. Look at your latest edits, dependency updates, configuration changes, and data changes.
Version control makes this easier. You can compare the current code with an earlier working version or temporarily test whether a recent change introduced the problem.
The key is to use the change history as evidence. A recent edit is a reasonable place to investigate, but don’t assume it is the cause until you’ve tested that idea.
9. Confirm the fix—and check nearby behavior
A bug disappearing once is not enough. Repeat the exact steps that originally reproduced it.
Then test a few nearby cases. If the issue involved an empty password, try a valid password and another invalid input. A fix for one case should not quietly break another.
Where possible, add a test that captures the bug. That way, if the same issue returns later, an automated check can catch it.
A useful test should describe the behavior you want, not the implementation detail you happened to change.
10. Know when to ask for help
Debugging independently is valuable, but struggling in silence for too long is not.
When you ask for help, share:- What you expected
- What happened
- How to reproduce it
- The relevant error message
- What you have already tried
- A small code example, if possible That gives someone else a clear starting point and avoids repeating steps you’ve already taken.
A quick debugging checklist
Before you finish, ask:- Can I reproduce the bug?
- Do I understand the exact expected and actual behavior?
- Have I read the full error message and relevant stack trace?
- Have I checked the values flowing into the failing code?
- Did I test a smaller example?
- Did I change one thing at a time?
- Have I confirmed the fix and checked nearby cases? ## The real skill is reducing uncertainty Good debugging isn’t about knowing every answer in advance. It’s about asking questions that make the problem smaller and clearer.
Reproduce the issue. Gather evidence. Follow the data. Test one idea at a time. Confirm the fix.
The next time a bug appears, try resisting the urge to rewrite the whole thing. Start with one precise question:
What do I know for sure, and what can I test next?
That question is often the fastest route to the answer.
Top comments (0)