How to debug

What is debugging, and why does most of your time go to finding rather than fixing?

Debugging means closing the distance between "it is broken" and "this line is wrong". In most bugs a beginner meets, the fix is one word or one symbol. The whole job is reaching that word.

There is a sharper definition that makes everything simpler: a bug is a place where what you believe about the program differs from what the program actually does. A program never behaves "strangely" and has no moods; it does exactly what you wrote. So debugging means finding the point where your picture parted company with reality.

That definition has a practical consequence. If a bug is a gap between belief and reality, anything that puts the two side by side is progress and anything else is not. Printing a value is progress. Changing a line in the hope that it might fix things is not; that is gambling, and its worst property is that you learn nothing even when you win.

And one thing nobody tells beginners: your speed at debugging depends far less on how well you know the language than on how disciplined your method is. An experienced developer walks the same five stages, just discarding irrelevant guesses faster.

Why does everything start with making the failure repeatable?

A reliable repro means you can write down: "do this, and this happens." Until you have that sentence, nothing else means anything. Whatever you change afterwards, you will not know whether it is fixed or whether it simply did not happen this time.

A good repro has three things: the shortest path that reaches the failure, the exact data the failure happens with, and a defined starting state. "Sometimes it errors when placing an order" is not a repro. "With a freshly created user, an empty basket and an expired discount code, the submit button returns a 500" is a repro, and that sentence alone has done half the work.

Now a trap that has cost time on this very site and is written into our own engineering notes: your repro may not be testing what you think it is testing. When we delete a page cache file here, the web server keeps serving that deleted file for up to a minute, because it caches the result of the file lookup for 60 seconds. So if you open the page straight after clearing it, you see the old page and conclude that clearing did not work. It did work; you looked too early.

This is a specific case of a general mistake: between the thing you did and the thing you see, there is a layer you do not know about. The browser cache, the network cache, the code cache, an old copy of the file on another server. The first question to ask is not "why does it not work", it is "am I even running the thing I changed?" In PHP code the simplest way to prove it is to put a deliberately wrong print line in and see whether it shows up at all.

How do you actually read an error message?

Most beginners do not read the error message. They look at it, flinch at the red, and go straight to a search engine. Yet the message usually says exactly what you need, and nobody taught them the order to read it in.

An ordinary error has three parts. The type says what class of thing happened. The text says what happened to what. The location gives a file and a line number. Behind them there is usually a stack trace, the chain of functions that were called to get here.

Do not read the stack from the bottom up. The line closest to the error is at the top, since most languages list newest first. But what you are really looking for is not the closest line; it is the closest line you wrote yourself. If the first five entries belong to a library you did not write, the problem is usually not there; it is in the first line of your own code that called that library and handed it something wrong.

And the most important point in this section: the line number in an error is where the problem was noticed, not necessarily where it was created. If line 42 says a variable is empty, line 42 is fine; the place that should have filled it and did not is higher up. An everyday example: "calling a method on null" is almost never about the line it is printed on. It is about the line you expected to build that value, which returned nothing instead, and there may be ten function calls between the two.

What do you do when nothing errors at all?

The hardest bugs are the ones that do not error. The program runs, finishes, and the result is wrong or there is no result at all. The first thing to establish here is whether there really is no error, or whether there is one and you cannot see it. Those are very different, and in most cases the answer is the second.

Three usual places an error goes missing: a language setting that turns error display off on the server, a catch block that swallows the error and does nothing with it, and the wrong output channel. That third one is the least known and eats the most time.

A command line program has two separate output channels and an exit code. If you only read the first, a broken tool and an empty result look identical to you. A real example from this server, on the day this lesson was written: we ran the WordPress database query command and it produced zero bytes on standard output. Concluding "there are no rows" would have been wrong. The exit code was 1, and the error channel said it could not connect to the database at all.

So the rule of this section: an empty result is not evidence of absence. Before you trust an empty output, look at the exit code and read the error channel separately.

The same mistake has a simpler form that happens to everyone: your search tool finds nothing and you conclude the thing does not exist. On this very site, the robots tag on the home page is printed with single quotes. Search for it with double quotes and you get zero results and declare the tag missing. The tag is there. Your pattern was wrong, and the tool said exactly that: "what you asked for was not found." The rest you added yourself.

Halving: the shortest route to that one line

Once you have a repro, you have read the error, and you still do not know where it is, there is a method that almost always works and does not depend on how clever you are: halve it.

The logic is simple. If your program is a thousand lines and you do not know where the problem is, you have a thousand places to look. Disable half of it and if the failure is still there, five hundred places are gone. Ten halvings take a thousand down to one. Ten steps, for a problem that took hours of staring.

You will meet three practical forms of this in your own day. On code: comment out half the functions or return early. On data: cut the thousand-row input file to five hundred and see whether the failure survives, until you reach the smallest input that still fails; that input is half the answer by itself. On time: if it worked yesterday and not today, search between two versions rather than between a thousand lines. Git has a command for exactly this, git bisect, which does the halving for you and asks you only to say, after each step, whether that version was good or bad.

And one point that saves beginners: while halving, always keep the smallest example that still fails to one side. A ten-line file that produces the same error is infinitely more valuable than a thousand-line project that produces the same error, because there is nothing left in it to distract you. If you go on to ask someone for help, you send those ten lines and not the whole project.

Change one thing at a time, and write down what you tried

Once you are down to a small area, you will be tempted to change three things at once to be done sooner. If it works, you do not know which one fixed it. If it gets worse, you now have three variables instead of one. This is the one place where hurrying reliably slows you down.

The right method has a fixed shape. Form a hypothesis that can be proven wrong: not "I think it is the cache" but "if it is the cache, clearing it will change the result." Then pick the cheapest test that confirms or kills that hypothesis, change that one thing only, and look at the result. If the hypothesis was wrong, put the change back. Beginners skip that last part, and an hour later the code is full of unrelated edits that are themselves new bugs.

And a habit nobody believes in until they try it once: open a text file and write down everything you tried and what happened. Three words per line. It gives you three things: you stop testing the same thing twice, you do not start from zero when you come back tomorrow, and if you have to explain the problem to somebody, the explanation is already written.

Very often writing the explanation is what produces the answer. People even have a name for it: explaining the problem out loud to a neutral listener, even if that listener is a plastic toy on the desk. The reason is that explaining forces you to say your assumptions one at a time, and the bug is usually in the assumption that felt so obvious you never said it out loud.

Print or a debugger? And what about a live server?

You have two main tools, and arguing about which is better is pointless, because they do different jobs.

Printing means adding a line that shows the value of a variable. Its advantage is that it works everywhere, from a small script to a server you have no access to, and needs nothing installed. Its drawback is that each run gives you one snapshot, and if you put it in the wrong place you have to run again. For most everyday bugs it is enough, and whoever says professionals do not print has not watched professionals up close.

A debugger stops the program in the middle and lets you see every variable at once and step forward line by line. It earns its keep when you do not know where to print in the first place, or when the path through the code has so many branches that you cannot tell which one was taken. Learning it costs half a day and you get that half day back quickly.

On a live server neither works in its usual form. You cannot attach a debugger and you must not print something a visitor will see. There you have one thing: the log. And here is a common mistake worth telling once: writing to the log does not mean being seen. The server may have error levels set so your message is never recorded, or the log file may be somewhere you would not think of. Before you go hunting a bug, write one meaningless line to the log and find it. Until you have seen that line, not seeing the other messages proves nothing.

Three things that must never go into a log, while we are here: passwords, tokens, and personal user data. A log is a file several people read and it stays around for a long time.