I know, I know.

Debugging is a boring topic to read.

I could have written about whatever is trending this week - JEV, Gemini 4, some new AI model, agent framework, or another shiny tool everyone is talking about.

That probably would've gotten more clicks.

But if you're trying to become a genuinely good engineer, I'd rather you understand this.

Because once you get good at debugging, the real world becomes much easier.

Tools will change. Frameworks will change. The stack you use today might be completely different three years from now.

But production will still break.

An API will suddenly start returning 401.
A deployment that worked yesterday will start throwing 500.
A container will be running perfectly fine but somehow have no logs.
A script will fail with an error that makes absolutely no sense at first.

And in those moments, knowing another Kubernetes command or memorising another system design diagram won't save you.

How you think will.

Imagine someone tells you:

That doesn't give you much to work with.

Instead, write down what is actually happening.

Now you have something you can investigate.

This distinction matters.

A 401 Unauthorized is something you know happened.

That's only a guess.

Other possible reasons could be:

Debugging gets much easier when you stop treating your first guess like the answer.

For a small script, the same idea applies.

Instead of:

Write:

You now have a specific failure that you can reproduce.

That's already a much better starting point.

You don't need a complicated debugging framework.

Use these five steps.

Be specific.

Bad:

Better:

Bad:

Better:

The more clearly you describe the problem, the easier it becomes to decide what to check next.

A lot of bugs appear shortly after something changed.

Check things like:

This doesn't mean the latest change is automatically the cause.

It just gives you somewhere useful to start looking.

Don't try to explain the entire problem at once.

Pick one thing that could explain what you're seeing.

For example:

That's enough.

Now ask:

If the client isn't sending an Authorization header, inspecting the request should show that the header is missing.

So run a check that answers exactly that question.

This is where good debugging starts to feel very different from guessing.

If the header is missing:
> investigate the client.

If the header exists:
> stop touching the client and move to the server.

Each result should make your search area smaller. That's the goal.

Suppose your local API should return:

but you're getting:

A random approach might look like this:

Maybe it starts working. But which change fixed it? You don't know.

And worse, maybe disabling the auth check was the thing that made it work.

That's not really a fix.

Instead, start with one possible reason:

Now ask:

You should see that the outgoing request doesn't contain an Authorization header.

So inspect the request:

With curl -v, outgoing request lines start with > and response lines start with <.

Look for something like:

If the header isn't there, you just narrowed the problem down.

Now check the client.

Maybe your code expects:

but your environment only contains:

That's a useful finding.

You went from:

to:

Much better.

But what if the header is present? Good.

Your original guess was wrong. Stop changing client code. Move to the server.

Check:

A wrong guess is still useful when it tells you where not to look.

One thing to remember: curl -v shows what the client tried to send. If there is a proxy between the client and server, the request could still be changed later.

Also be careful before sharing verbose output. It can contain tokens, cookies, and other secrets.

Here's another common one.

Your container is running.

Requests to the application are failing.

So you run:

And get nothing useful back.

It's easy to conclude:

But that's not necessarily true.

A better question is:

docker logs normally shows output Docker captured from the container process, usually stdout and stderr.

But an application might instead write logs to:

or send them somewhere else entirely.

So start with one possible reason:

Now inspect what Docker actually started:

If the image has a shell, you can inspect the container:

Then check the application's configuration.

Look for:

Maybe you discover:

Now you know why docker logs looked empty.

The application was logging. Docker just wasn't showing those logs.

The exact commands will differ between applications and container images.

Some containers don't even include a shell. That's fine.

The useful part is the order:

That's debugging.

This becomes especially important in production.

Imagine you deploy a new release.

A few minutes later:

starts returning:

Customers are affected. You roll the release back. The error rate drops. Users can check out again.

But what did you actually learn?

You know:

You do not automatically know:

The rollback may also have changed:

So keep two separate questions in your head.

That might mean:

That investigation can continue after the system is stable.

During an incident, write down what you actually know:

Notice the last line.

There's nothing wrong with that.

It's much better than pretending your first theory is already confirmed. This is why incident response and root-cause analysis are different jobs.

During an outage, your first priority may be getting the service healthy again.

Understanding exactly why it happened can come next.

One habit I see beginners develop is collecting debugging commands.

These are useful tools.

But knowing commands isn't the same thing as knowing how to debug.

Before running one, ask:

Instead of:

Think:

Instead of:

Think:

Instead of:

Think:

Same commands.

Very different way of thinking.

As you get better, your debugging process becomes less random.

Something breaks.

You ask:

Then:

Then:

Then:

You run the check.

Then you use the result to decide what comes next.

Over time, you'll naturally get faster because you've seen more failure patterns.

You'll recognise things like:

Experience helps.

But even experienced engineers don't know the answer immediately every time.

They're usually just better at narrowing the problem down.

Good debugging isn't knowing 100 Linux commands.

It's being able to look at a broken system and keep making the problem smaller.

Whenever you're stuck, ask yourself:

1. What do I actually know?
2. What am I assuming?
3. What's the smallest thing I can check next?

Get good at those three questions and debugging, and I promise you’d climb up the career ladder much faster than others.

👋 Find me on Twitter | Linkedin | Connect 1:1

Thank you for supporting this newsletter.
Y’all are the best.