Claude Code /debug: Trace Mystery Errors with Logs

When you use Claude Code, moments come when you wonder, "why does it keep stalling?" or "what just went wrong?" It's frustrating because the screen says nothing in particular. That's when you use /debug. It pulls the inner workings (logs) that are usually hidden out onto the screen, so you can peer into what is running and how.

Definition (what it is)

/debug is a command that turns on the debug log (a record of what the program is doing internally) and analyzes the problem.

Normally Claude Code shows only the results cleanly and hides the internal workings. When you turn on /debug, those hidden workings are recorded in detail on the screen or in a log file. You can get clues like where it stalled or which tool it got stuck calling.

How to use it (by difficulty)

Basic — just turn it on

/debug

Entering just this starts collecting logs. As you work afterward, far more detailed records of operation pile up than usual.

Applied — describe the symptom too

/debug it keeps stalling

If you write the symptom you're experiencing alongside it, the analysis focuses on that symptom. Just writing one line about "what seems off" makes the direction of the trace much clearer.

Common pitfalls (only when applicable)

• Debug logs contain fairly detailed information like work paths and command contents. When sharing logs as-is with someone else, scan them once to make sure no sensitive information (API keys, passwords, etc.) is mixed in.
• /debug is not a command that "fixes" things — it's a command that "shows the cause." After turning on the log, you have to reproduce the problem situation once more to catch the clues.

Real-world example

Odd behavior that only shows up occasionally is the most troublesome. In that case, turn on the log with /debug first and retry the task where the problem occurred. Looking at the logs that piled up at that moment, you can find the spot where you think "ah, it stalled here."

Taking it further

Since you can peer directly at the cause through the logs, instead of vaguely saying "it doesn't work," you can pin down "it got stuck here." If you can't solve it on your own, sending the clues gathered with /debug together with the /feedback (bug report) command also helps with improvement.

Summary

/debug is a command that pulls Claude Code's hidden workings out onto the screen. When you hit a mysterious stall or odd behavior, turn it on and reproduce the problem to get clues for tracing it.

Based on Claude Code v2.1.154 (2026.05)