Claude Code Error Logs: Where to Find and Read Them (2026)

When Claude Code fails and the terminal output is not enough, the log files hold the full story. Every API call, tool invocation, error, and internal state change is recorded. Knowing where these files live and how to read them is the difference between a 5-minute fix and an hour of guessing. This guide covers log locations on every OS, the log format, filtering techniques, and the --verbose flag for real-time debugging. For instant error identification, paste any error from your logs into the Error Diagnostic Tool.

Log File Locations by OS

macOS

~/.claude/logs/
# Example: ~/.claude/logs/session-2026-04-26T14-30-00.log

Each session creates its own log file with a timestamp in the filename. The most recent session is always the last file sorted alphabetically.

# Find the latest log
ls -lt ~/.claude/logs/ | head -5
# Open the latest log
cat ~/.claude/logs/$(ls -t ~/.claude/logs/ | head -1)

Linux

~/.claude/logs/
# Same structure as macOS
# On some distributions, XDG paths may apply:
$XDG_DATA_HOME/claude/logs/
# Which defaults to:
~/.local/share/claude/logs/

Windows (WSL)

# Inside WSL:
~/.claude/logs/
# Native Windows (if using Node directly):
%USERPROFILE%\.claude\logs\
# Typically: C:\Users\YourName\.claude\logs\

Additional Log Sources

Beyond session logs, Claude Code writes to these locations:

# MCP server logs (separate from main logs)
~/.claude/mcp-logs/
# Crash dumps (created on fatal errors)
~/.claude/crash-reports/
# Configuration change audit log
~/.claude/audit.log

Understanding the Log Format

Every log entry follows a structured format:

2026-04-26T14:30:15.123Z [INFO] [session:abc123] Message sent to API
  model: claude-sonnet-4-20250514
  input_tokens: 4521
  max_tokens: 8192
2026-04-26T14:30:16.456Z [ERROR] [session:abc123] API request failed
  status: 429
  retry_after: 60
  message: Rate limit exceeded

The key fields are:

  • Timestamp – ISO 8601 format, always UTC
  • Level – DEBUG, INFO, WARN, ERROR, FATAL
  • Session ID – links all entries for a single session
  • Message – human-readable description
  • Metadata – indented key-value pairs with context

Filtering Logs for Specific Errors

Raw log files can be thousands of lines. Use these filtering patterns:

Find All Errors

grep -E "\[ERROR\]|\[FATAL\]" ~/.claude/logs/session-*.log

Find Token Usage

grep "input_tokens\|output_tokens" ~/.claude/logs/$(ls -t ~/.claude/logs/ | head -1)

Find API Failures

grep -A 3 "API request failed" ~/.claude/logs/$(ls -t ~/.claude/logs/ | head -1)

Find MCP Issues

grep -i "mcp\|server.*disconnect\|server.*error" ~/.claude/logs/$(ls -t ~/.claude/logs/ | head -1)

Find Permission Errors

grep -i "EACCES\|permission denied\|EPERM" ~/.claude/logs/$(ls -t ~/.claude/logs/ | head -1)

Tail Logs in Real Time

# Watch the current session's log as it writes
tail -f ~/.claude/logs/$(ls -t ~/.claude/logs/ | head -1)

Using –verbose for Real-Time Debugging

The --verbose flag outputs maximum detail to stderr during execution:

claude --verbose

Verbose mode adds:

  • Full HTTP request/response headers (API key redacted)
  • Tool input/output payloads
  • Token count per message
  • Context window usage percentage
  • MCP server communication details
  • File read/write operations with paths

For targeted debugging, redirect verbose output to a file while using Claude Code normally:

claude --verbose 2>/tmp/claude-verbose.log
# Work normally in the session, then check:
grep "ERROR" /tmp/claude-verbose.log

Log Rotation and Cleanup

Claude Code does not automatically rotate or delete logs. Over months of use, the logs directory can grow to several gigabytes.

Check Log Directory Size

du -sh ~/.claude/logs/

Clean Old Logs (Keep Last 7 Days)

find ~/.claude/logs/ -name "session-*.log" -mtime +7 -delete

Archive Instead of Delete

mkdir -p ~/.claude/logs/archive
find ~/.claude/logs/ -name "session-*.log" -mtime +7 -exec mv {} ~/.claude/logs/archive/ \;
# Compress the archive
tar -czf ~/.claude/logs/archive-$(date +%Y%m%d).tar.gz ~/.claude/logs/archive/
rm -rf ~/.claude/logs/archive/

Correlating Logs with Crashes

When Claude Code crashes, follow this workflow:

  1. Find the crash session log:
ls -lt ~/.claude/logs/ | head -1
# The newest file corresponds to the session that crashed
  1. Find the last error before the crash:
grep -n "ERROR\|FATAL" ~/.claude/logs/[crash-session].log | tail -5
  1. Read the context around that error:
# If the error is on line 450:
sed -n '440,460p' ~/.claude/logs/[crash-session].log
  1. Check the crash report (if generated):
cat ~/.claude/crash-reports/$(ls -t ~/.claude/crash-reports/ | head -1)

The crash report includes the Node.js process exit code, signal (SIGKILL for OOM, SIGSEGV for memory corruption), and the last 20 log entries before termination.

Try It Yourself

Reading logs is powerful but slow. The Error Diagnostic Tool takes the error message from your log and instantly returns the fix, root cause, and prevention steps. Paste the [ERROR] or [FATAL] line directly from your log file.

Try the Diagnostic Tool –>

Common Questions

Can I change where Claude Code stores its logs? Not directly through Claude Code's configuration. However, you can create a symlink: ln -s /your/preferred/path ~/.claude/logs. Claude Code will follow the symlink and write logs to your preferred location.
Do logs contain my API key or sensitive data? API keys are redacted in logs (shown as sk-ant-***). However, logs do contain your prompts, file paths, and tool outputs. Treat log files as sensitive and do not share them publicly without redaction.
How large do Claude Code log files get? A typical 30-minute session produces a 2-5MB log file. Heavy sessions with verbose mode enabled can reach 50MB+. Run du -sh ~/.claude/logs/ periodically and clean files older than 7 days.
Is there a GUI log viewer for Claude Code? No official GUI exists. For a better reading experience, pipe logs through less -R for paged viewing, or open them in VS Code which provides syntax highlighting for structured log formats.

Estimate usage → Calculate your token consumption with our Token Estimator.

Configure MCP → Build your server config with our MCP Config Generator.