Debugging

Debugging is the process of finding the cause of a known problem in a program, and fixing it. The hard part is usually the diagnosis rather than the correction.

To debug well, we distinguish four things that we loosely refer to as 'the bug':

• A mistake is the human (or AI) act that started it all.
  Example You misremembered that list indices start at 1.
• A defect is the resulting error in the software. This is what most people mean by 'a bug'. It is usually in the code, but it can also be in configuration, in data left by an earlier version, in a dependency, in the deployment, or in a requirement that was wrong to begin with.
  Example A loop that starts counting from the wrong index.
• An infection is the resulting error in the program state at run time. When the defective line executes, some variable now holds a wrong value. Infections can spread; for example, an 'infected' variable holding a wrong value can cause another variable to hold a wrong value in turn.
• A failure is the externally visible wrong behavior.
  Example A total shown to the user that is too small, or a crash.

These four form a chain, and each link can be far from the next:

A big part of debugging is the backward search for the defect by starting from the observed failure.

This chain also explains why bugs hide: a defect infects the state only when that line executes, and an infection becomes a failure only if it propagates out to something observable. So, a defect can sit in daily-executed code for months unnoticed.

class Cart {
    private final List<Item> items = new ArrayList<>();

    void add(Item item) {
        items.add(item);
    }

    List<Item> getItems() {
        return items;
    }

    int computeTotal() {
        int total = 0;
        List<Item> pending = getItems();
        while (!pending.isEmpty()) {
            total += pending.remove(0).price();
        }
        return total;
    }
}

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

Why debugging is hard

Some factors that make debugging hard are:

• The distance between defect and failure: the crash site is not always the crime scene; so focusing on the code around the error message might not always lead you to the cause.
• You cannot inspect everything — a running program holds an enormous amount of state, changing at every step, and choosing which small part to look at is hard.
• Wrong assumptions that caused the bug can hamper debugging as well: if a wrong assumption caused you to create the defect, debugging while holding the same wrong assumption can reproduce the same blind spot. This is why debugging must be driven by evidence from the running program, not by reasoning alone.

How not to debug

• Bad Stare and hope — reading the code and waiting for the bug to reveal itself. This inspects the code but not the state. It is fine as a 30-second first try but a poor use of time for an extended attempt.
• Bad Shotgun debugging — changing whatever looks suspicious and re-running to see whether it helped. Most such changes neither confirm nor eliminate any explanation, and unrelated edits accumulate.
• Bad Fixing the symptom instead of the cause. The failure goes away and the defect stays.
  Example Special-casing the input that fails, or wrapping the crash in an empty catch block.
• Bad Keeping no record of what you tried. Without notes you will re-test explanations you already eliminated, lose your place when interrupted, and be unable to hand the problem over.

What these have in common is that they produce activity without producing useful information. A productive debugging step is one that rules something out.

Adding temporary print statements is not necessarily bad. A few prints chosen to answer a specific question are legitimate, and in production, embedded, or concurrent settings they are sometimes the only tool available. However, this technique alone is not enough to tackle most non-trivial bugs.

Systematic debugging involves following tasks, whose first letters make up the mnemonic TRAFFIC (credit: Andreas Zeller).

• T
  rack — state what the correct behavior is, and record the problem somewhere durable.
• R
  eproduce — make the failure happen on demand.
• A
  utomate and simplify — turn the reproduction into a one-step test, and reduce it to the smallest case that still fails.
• F
  ind origins — list the places where the state could first have gone wrong.
• F
  ocus — pick the most likely candidate origin, and state what it predicts.
• I
  solate — run the check that decides if the candidate origin is the actual origin, and conclude.
• C
  orrect — fix the cause, confirm it, and guard against recurrence.

TRAFFIC is a map rather than a mandatory sequence. Some tasks can be done in a loop before it lands on the cause, and you can reorder the other tasks as you see fit.

The most common mistake is jumping straight to C. Starting at 'correct' and working backwards is how shotgun debugging happens. This text below covers the six tasks TRAFFIC except C, which is covered separately.

Track

The first step of debugging should be stating what the correct behavior is, and why. Without that you have nothing to compare the program against, and you risk searching code that was right all along. State the expectation in a testable form: for this input, that exact result.

Reproduce

A reliable reproduction makes every experiment cheap and is a way to confirm afterwards that the fix worked. Reproducing means recreating everything the failure depends on, e.g., the input data, the program version, the environment and , the sequence of actions, and the starting state, such as leftovers from a previous run.

When you cannot reproduce a failure you can still investigate it. Instead of running experiments you mine the evidence left behind: stack traces, logs, , , and the differences between runs that failed and runs that did not. The immediate goal becomes making the failure more observable or more frequent. Moving a bug from 'once a week' to 'one run in five' is real progress.

Automate and simplify

Automate the reproduction as a test case as early as you can. Turning "launch the app and perform these six steps" into a one-second command is what makes the hypothesis loop cheap, and it can become the regression test once you have a fix.

Why simplify? The smaller the failing case, the smaller the search space -- every element you can remove while the failure persists eliminates a whole category of possible causes. Some directions you can try:

• Shrink the input space: Cut the input space in half, test each half, keep whichever still fails, repeat. When it works it is very cheap, and needs no insight into the code. But halving does not always work: sometimes neither half fails, because the failure needs two elements the halving separated.
• Simplify the code path: Strip away unrelated features, configuration, and calls until only the failing core remains. Now you have less code to search for the defect.

Find origins

An origin is a place where the state could first have gone wrong: before it the state is correct, after it the state is infected, and the cause sits at that boundary. This step often produces a list of candidate origins rather than a single answer. Some techniques you can follow:

• Reason backwards from the wrong value. Ask which statements could have produced it, then which produced their inputs. Following data and control dependencies backwards is called backward slicing — it narrows the candidates rather than pinpointing them, since a slice reliably contains every statement that could be responsible, usually along with some that could not.
• Explain the code to someone, line by line (aka rubber duck debugging): explaining the code to a patient friend, in a written explanation, to an AI, or even to an inanimate object like a rubber duck works for a real reason: articulating what each line does forces you to state assumptions you had taken for granted, and you often spot the wrong assumption mid-sentence ("...then, that object is passed to ... wait, that can't be right ... that object should not cross this boundary!").
• Read the evidence you already have before generating candidates from the code alone. An exception message names the expression that failed, a stack trace names the calls that led there, and a diff names what changed recently.

Focus

Candidate origins are not equally likely, and the order you check them in decides how long the search takes.

• Prefer recently changed code to long-stable code, your code to library code, and library code to the compiler or the operating system. This is a starting bias rather than a rule (i.e., it is possible for the bug to be in the library code or even the OS, although less likely).
• Turn the chosen origin into a prediction before you check it. State what you would observe if it is guilty and what you would observe if it is innocent. This makes your debugging more systematic and helps you narrow down the candidates faster.

Iisolate

Isolating means running one check, discarding the part of the search space it rules out, and repeating until you find what needs to be fixed.

• Binary search over the execution can be used to find when the state gets infected. Pick a point roughly halfway through the suspect region, pause, and ask one question: is the state already wrong? If yes, look earlier; if no, look later. Each check roughly halves the region still under suspicion.
• Binary search over versions can be used to find when the code used to work. If it passed last week, the cause is in one of the commits since -- bisect the history rather than the code. git bisect automates this, and works best with small, self-contained commits. Martin Fowler calls this Diff Debugging.
• Swap a suspect component for one you trust. If the failure survives the swap, that component is very likely not responsible.
• Change one thing at a time, or the outcome will not tell you which change produced it.
• Record the conclusion, then start the next turn of the loop from the narrowed region until you find what needs to be fixed.

Correct

Covered in a separate section, titled Fixing.

Do not settle on a fix until you can explain the whole failure. Temporary changes made as experiments are fine, but a change you intend to keep needs a causal account that explains every observed behavior. The strongest check is to predict, before making the change, exactly what will be different afterwards, then verify that prediction. A fix that works for reasons you cannot state can fail again.

Fix the cause, not the infection and not the failure. Special-casing the failing input or clamping a bad value removes the symptom and leaves the cause. Also consider whether you have a coding error or a design error: a coding error is code that does not do what you intended -- whereas a design error means the intention itself was wrong. The real remedy for the latter is a design change, not a code fix.

Which change counts as 'the fix' is sometimes a genuine choice. Making that choice consciously helps ensure that the fix does not degrade other aspects of the system (e.g., its design integrity).
Example In the cart example you could make getItems() return a copy, or make computeTotal() iterate without mutating. Both remove the failure; they differ in which contract you treat as authoritative.

Once you have a candidate fix, finish the job:

• Look for the defect's relatives — the same mistake was probably made in the sibling method, the other branch, or the block copy-pasted from this one.
• Verify against the reproduction, then run the full test suite. A fix that resolves your failure while breaking two other things is not a fix.
• Add a regression test that fails before the fix and passes after it. If you automated the reproduction earlier, you already have it.
• Remove your temporary probes — stray print statements, leftover , commented-out experiments. Assertions and logging you added deliberately to stay are not temporary probes; keep those.
• Commit the fix on its own, apart from unrelated cleanup, so that the history stays bisectable for the next bug.

Every way of looking inside a running program is a probe — a means of answering one specific question about its state. Here are some widely used probes:

• Print statements are the cheap to start with and expensive to iterate with. They are easy to insert, but each needs an edit-build-run cycle, each edit is a chance to introduce a fresh defect, and leftovers reach production if you forget them.
• Logging is the disciplined, permanent form of printing. and , log statements can stay in the code — so they are still there when the failure happens on a user's machine at 3 a.m., where no debugger can reach.
• Assertions are probes that check themselves. Rather than printing a value for you to examine, an assertion states what it should be and fails immediately when it is not, turning a silent infection into a loud, located failure. If you use Java's assert statement, enable assertions in your run configuration or it will do nothing; test-framework (e.g., JUnit) assertions are separate and always run during testing.
• A debugger is a tool that can attach itself to an executing program and can ask questions interactively, without changing the code at all.

The useful question is never "print statements or debugger or ___?" but "what is the cheapest probe that answers this question?" Some probes come out once the bug is found (e.g., a temporary print statement); others are meant to stay (e.g., a permanent log statement).

Using a debugger

A debugger is a tool that lets you pause a running program, then inspect and control it from the inside, without modifying its code. You choose the lines where the program should stop. When execution reaches one of them, the program freezes mid-run and waits for you. You can then look at the current values of its variables, see the chain of method calls that led there, and let it continue one line at a time. Most IDEs, such as IntelliJ IDEA, come with a debugger built in. There are also standalone debuggers that you control by typing commands, such as GDB for C and C++, and jdb for Java.

A debugger works from outside your program, which is what makes it different in kind from printing. The debugger runs as a separate process. It either launches your program under its control or attaches to one that is already running, then asks the operating system, or the JVM for a Java program, to pause the program at the chosen lines and report its state back. Your code stays untouched throughout. With print statements, every new question about the program means adding another print, rebuilding, and re-running. With a debugger, the paused program keeps all its state, so asking one more question costs seconds rather than another edit-build-run cycle.

Breakpoints determine where the program pauses. A breakpoint is a marker that tells the debugger to stop the program at a particular spot. In an IDE, you usually set one by clicking in the margin next to a line number, which puts a red dot there. In GDB, you type a command such as break main.c:42 instead. Either way, the debugger keeps track of the breakpoint, so your source file does not change. Breakpoints take effect only when you start the program through the debugger, e.g., with IntelliJ's Debug button rather than Run. Started the normal way, the program runs straight past them. Breakpoints come in several kinds:

• A line breakpoint pauses when execution reaches a given line.
• A conditional breakpoint pauses only when a condition holds. This makes debugging the 4137th iteration of a loop feasible at all, and it is the feature beginners most often do not know exists.
  Example Pausing only when i == 4137.
• An exception breakpoint pauses at the moment an exception is thrown, before the stack unwinds and discards the state you need.
• A field watchpoint pauses when a field's value changes rather than at a location — the right tool for "what is setting this to null?"

Stepping commands determine how execution advances. Once you have examined the paused program, a stepping command lets it run a little further and then pauses it again, so you can see what changed. In an IDE, each command has a toolbar button and a keyboard shortcut. The common ones are:

• Step over runs the current line as one step, including any methods it calls, and pauses at the next line.
• Step into moves into the method called on the current line and pauses at the first line of that method.
  Example If the current line is total += item.price();, step over pauses at the line after it, while step into pauses inside price().
• Step out runs the rest of the current method and pauses back in the method that called it.
• Run to cursor keeps running until execution reaches the line your cursor is on, like a one-time breakpoint.
• Resume keeps running until the program reaches the next breakpoint or ends.

Inspection views let you examine details of the state the program is currently paused at. Some common inspection views:

• The call stack shows how execution reached this point, and selecting any frame reveals that method's variables. The cause is often several frames above where the program stopped.
• The variables view shows the values currently in scope, and watches track a chosen expression as you step.
• evaluate expression runs arbitrary code at the paused point, turning passive inspection into a live experiment: you can test a hypothesis without editing or restarting. One caution — evaluating really does run the code, so calling a method that mutates state, or setting a variable by hand, changes the program you are observing.

AI assistants are useful for some parts of debugging and unreliable for others. They are good at explaining unfamiliar error messages, proposing candidate hypotheses, and serving as an always-available rubber duck. They are unreliable at diagnosing a defect in code they cannot run, and will produce confident, fluent, incorrect explanations. A systematic method is what makes them safe: treat any suggestion as a hypothesis, insist it be falsifiable, and verify it against the running program yourself.

Reading stack traces

A stack trace is a precise report of where a program failed and the call path that led there. Read it in this order:

1. The exception type and message, which frequently name the problem outright.
2. The topmost frame in your code — not the topmost frame overall, which is usually library or platform code doing exactly what it was asked.
3. The chain of callers below it, which shows how execution arrived there.

The top of the trace is where the failure surfaced, but the cause is often further down, in whichever frame passed the bad value along. In wrapped exceptions, read the Caused by: chain from the bottom up.

Some common Java exceptions and what they usually mean: