Product case study · November 12, 2026
Turn a Claude Code failure into a useful debug report
Capture a Claude Code failure with --debug-file, compare the log with what happened, and prepare a redacted report without guessing the cause.

Capture one reproducible failure before changing settings. A useful report connects the trigger, observed result and relevant log excerpt.
Claude Code starts, but something inside the session fails. You retry, change a setting, restart, and try again. By the time you ask for help, you cannot remember which error came before which change.
Give the next attempt a narrower job: capture one failure well enough that someone else can investigate it. You need the action that triggered it, what you observed, and a small piece of supporting evidence. A debug log can help with the third part; it does not automatically explain the first two.
This walkthrough is for Bash on macOS, Linux or WSL with Claude Code already installed and authenticated. Official sources checked November 12, 2026. The installed CLI’s help was checked for --debug-file, and the shell setup was verified locally. The Claude interaction below is documentation-backed guidance, not a reported end-to-end failure reproduction or successful repair.
Decide what to reproduce
Write one sentence before opening another session:
When I [specific action] in [practice folder], I expect [observable result],
but I see [exact message or behavior].
Choose an action that is safe to repeat. For example, a tool failing to read a disposable file is a better first exercise than retrying a deployment whose outcome is unclear. If the original action could have sent, published or charged something, establish its outcome before attempting it again.
Keep the starting conditions steady. Do not update the CLI, replace configuration and change the prompt between the original failure and your capture. Those may be reasonable later experiments, but they make this comparison harder.
If claude does not start at all, begin with the installation check. This article is about evidence from a session that can launch.
Give this attempt its own log
In an ordinary terminal, change into the affected practice folder. Then run this block:
capture_dir=$(mktemp -d /tmp/claude-debug-capture.XXXXXX)
chmod 700 "$capture_dir"
claude --version > "$capture_dir/version.txt"
printf 'Capture directory: %s\n' "$capture_dir"
claude --debug-file "$capture_dir/session.log"
Save the printed path. It is outside your repository, so you are less likely to commit the raw log accidentally. The directory permissions limit access by other ordinary local users; they do not sanitize its contents or control what Claude sends to its provider.
Anthropic’s CLI reference documents that --debug-file selects a log path and enables debug mode. You do not need a separate --debug flag for this capture. If your installed version rejects the option, check claude --help before continuing rather than assuming a log was created.
Review the workspace and any permission prompts as usual. Logging is not permission to broaden what the agent may do. For a command failure, adapt this prompt:
Reproduce only the specific failure described below, once.
Do not edit files, change settings, install dependencies or retry automatically.
Tell me the exact action attempted and its observed result.
Separate direct observations from possible explanations.
Failure to reproduce: [your description]
Replace the bracketed description before sending. If the symptom is a missing integration rather than a command failure, inspect that integration instead of asking Claude to manufacture an error.
After the attempt, note the time and the visible error. Exit the session normally. If it hangs, record that fact and use the documented troubleshooting path for hangs; do not start several more sessions to see whether one works.
Read the capture without assuming every warning matters
Back in the same terminal, check whether the file exists and has content:
if test -s "$capture_dir/session.log"; then
wc -c "$capture_dir/session.log"
less "$capture_dir/session.log"
else
printf 'No nonempty debug log at the expected path.\n'
fi
In less, search with /, move to the next match with n, and quit with q. Start with a distinctive part of your visible error or the name of the component involved. Inspect neighboring lines, not just the matching line.
A file with bytes proves that something was captured. It does not prove the attempted action succeeded, or that the log contains enough detail to diagnose it. Do not expect a stable log schema or every tool’s complete output. Keep the visible result alongside the diagnostic excerpt.
Use this distinction while reading:
| Observation | What it supports |
|---|---|
| Error appears after the action you recorded | A candidate event to investigate in that attempt. |
| Warning appears at startup, but the task later works | A warning exists; its connection to your symptom remains unproven. |
| Log has no matching event | The capture has not explained the failure. |
| Action succeeds on this attempt | The original problem was not reproduced under these conditions. |
For configuration trouble, Anthropic’s configuration debugging guide offers more targeted checks: /hooks lists loaded hooks, /mcp shows server status, and /status identifies active settings sources. Its /debug command can enable session logging and ask Claude to investigate. Use the check that matches your symptom; asking for an explanation still requires you to verify the evidence it cites.
Make a report someone can use
Keep the full capture private. Read any excerpt before sharing it: remove credentials, personal data, private file paths, internal URLs and proprietary content. An automated redaction pass can miss sensitive values, so review the final text yourself. Do not attach the whole log just because it looks technical.
Write a separate report using this outline:
CLI version:
Operating system and terminal:
Smallest safe reproduction:
Expected result:
Observed result and approximate time:
Relevant redacted excerpt:
What the excerpt establishes:
What remains unknown:
Changes made since the first failure:
Leave an unknown field explicitly unknown. If the problem disappeared, say so and preserve the conditions of both attempts. A report that admits an intermittent failure is more useful than a confident diagnosis built from an unrelated warning.
Anthropic’s troubleshooting overview routes different symptoms to installation, configuration and error-reference guidance, and lists /feedback as a reporting option. Choose the matching route after reviewing what you intend to share. This exercise does not submit anything automatically.
Once the evidence suggests a repair, change one relevant thing and repeat the original action with a new capture directory. Compare the actual outcome. A quieter log is welcome; completion of the task that failed is the result you were trying to recover.
Sources and verification
- Anthropic: CLI reference, checked November 12, 2026. Debug-file flag and launch behavior.
- Anthropic: debug your configuration, checked November 12, 2026. Targeted configuration inspection and in-session debugging.
- Anthropic: troubleshooting, checked November 12, 2026. Symptom routing, hangs and reporting options.
The hero is an AI-generated editorial illustration, not a screenshot or a diagnostic result.
Put this to work
Capture and interpret diagnostic evidence from one Claude Code session.
Try
Launch with --debug-file, reproduce a harmless failure once, and inspect the resulting file locally.
Prove it worked
Keep the trigger, version, observed result and supporting excerpt together; mark missing evidence explicitly.
Keep in view
- Write a diagnostic log to a known path outside your repository.
- Separate a visible failure from your theory about its cause.
- Prepare a small redacted report and a repeatable recheck.