Claude Code ガイド

Appearance

原文（日本語訳） ​

致命的エラーが表示される代わりに隠蔽されていた問題を修正しました。

原文（英語） ​

Fixed fatal errors being swallowed instead of displayed

概要 ​

Claude Code 2.1.39では、システムやAPIレベルで発生した致命的エラー（fatal errors）が適切に表示されず、ユーザーに通知されないまま隠蔽されていた問題が修正されました。修正後は、エラーの内容とスタックトレースが明確に表示され、問題の診断とトラブルシューティングが容易になりました。

修正された問題 ​

隠蔽されていたエラーの例 ​

  • APIリクエストの致命的失敗
  • メモリ不足エラー
  • ファイルシステムの重大な問題
  • ネットワーク接続の致命的エラー
  • 内部アサーションの失敗

実践例 ​

API接続エラー ​

bash
claude

# API エンドポイントに接続できない場合

# 修正前:
# （何も表示されない、または単に動作が停止）
# プロセスが無応答になる

# 修正後:
# FATAL ERROR: Failed to connect to Anthropic API
#
# Details:
#   Error: ECONNREFUSED 127.0.0.1:443
#   at TCPConnectWrap.afterConnect
#
# Possible causes:
#   - No internet connection
#   - API endpoint is down
#   - Firewall blocking the connection
#
# Stack trace:
#   at APIClient.request (api-client.js:234)
#   at Session.sendPrompt (session.js:89)
#   ...

メモリ不足エラー ​

bash
# 大規模なファイルを処理中

# 修正前:
# （突然終了、エラー表示なし）

# 修正後:
# FATAL ERROR: JavaScript heap out of memory
#
# Details:
#   Allocation failed - process out of memory
#   Attempted allocation: 512MB
#   Current heap size: 4096MB
#   Heap limit: 4096MB
#
# Suggestions:
#   1. Increase Node.js heap size:
#      export NODE_OPTIONS="--max-old-space-size=8192"
#
#   2. Process files in smaller chunks
#
#   3. Use streaming for large files

ファイルシステムエラー ​

bash
claude

# "Write the configuration to /root/config.json"

# 修正前:
# （無言で失敗）

# 修正後:
# FATAL ERROR: Permission denied
#
# Details:
#   EACCES: permission denied, open '/root/config.json'
#
# The current user does not have write permission to /root/
#
# Solutions:
#   1. Use a directory you have access to:
#      ~/config.json or ./config.json
#
#   2. Run with sudo (not recommended):
#      sudo claude
#
#   3. Change file permissions:
#      sudo chown $USER:$USER /root/config.json

ネットワークタイムアウト ​

bash
# 長時間実行されるタスク中にネットワークが切断

# 修正前:
# （無応答状態が続く）

# 修正後:
# FATAL ERROR: Network timeout
#
# Details:
#   Request timeout after 120000ms
#   Endpoint: https://api.anthropic.com/v1/messages
#   Request ID: req_abc123xyz
#
# Your session has been saved and can be resumed with:
#   /resume
#
# Troubleshooting:
#   - Check your internet connection
#   - Verify API status: https://status.anthropic.com
#   - Try increasing timeout: export CLAUDE_TIMEOUT=300000

エラーログの強化 ​

詳細なスタックトレース ​

修正後は、エラー発生時に完全なスタックトレースが表示されます。

FATAL ERROR: Unexpected token in JSON

Stack trace:
  at JSON.parse (<anonymous>)
  at parseResponse (response-parser.js:45)
  at APIClient.handleResponse (api-client.js:189)
  at IncomingMessage.<anonymous> (api-client.js:234)
  at IncomingMessage.emit (events.js:412)
  ...

Response body (first 500 chars):
  {"error":{"type":"invalid_request_error","messag...

Request details:
  Method: POST
  URL: https://api.anthropic.com/v1/messages
  Headers: {...}

エラーログファイル ​

bash
# エラーログの自動保存
# ~/.claude/logs/fatal-errors.log

# ログの確認
cat ~/.claude/logs/fatal-errors.log

# [2026-02-11T10:23:45.123Z] FATAL ERROR: API request failed
# Request ID: req_xyz789
# Error: 503 Service Unavailable
# Duration: 45230ms
# Retry attempts: 3

デバッグ情報の収集 ​

詳細モードの有効化 ​

bash
# より詳細なエラー情報を表示
export CLAUDE_DEBUG=1
export CLAUDE_VERBOSE=1
claude

# すべての内部処理とエラーが表示される

エラーレポートの生成 ​

bash
# エラー発生時に自動でレポートを生成
export CLAUDE_ERROR_REPORT=1
claude

# エラー発生時:
# Error report saved to: ~/.claude/error-reports/2026-02-11-102345.json
#
# To share this report:
#   claude report submit ~/.claude/error-reports/2026-02-11-102345.json

クラッシュダンプ ​

bash
# 重大なクラッシュ時のダンプファイル
# ~/.claude/crash-dumps/

ls -la ~/.claude/crash-dumps/
# -rw-r--r-- 1 user user 2.4M Feb 11 10:23 core.12345.dump
# -rw-r--r-- 1 user user  156K Feb 11 10:23 crash-info.json

リカバリー機能 ​

自動セッション保存 ​

致命的エラー発生時、セッション状態が自動保存されます。

bash
# エラー発生
# FATAL ERROR: ...
#
# Your session has been automatically saved.
# Resume with: claude --resume-last

# 再開
claude --resume-last

部分的なリカバリー ​

bash
# 一部のツール実行が失敗した場合
# FATAL ERROR in tool execution: Write
#
# Successfully completed:
#   ✓ Read file src/main.js
#   ✓ Analyzed code structure
#   ✗ Write changes (FAILED)
#
# Partial results saved to: ~/.claude/temp/partial-results.json
#
# You can retry with:
#   claude --retry-from-checkpoint

エラー通知設定 ​

デスクトップ通知 ​

json
// ~/.claude/settings.json
{
  "notifications": {
    "fatal_errors": true,
    "desktop_alerts": true
  }
}
bash
# 致命的エラー発生時にデスクトップ通知が表示される
# タイトル: "Claude Code Fatal Error"
# 内容: "API connection failed. Check logs for details."

外部ログシステムへの送信 ​

bash
# Slackへの通知
export CLAUDE_ERROR_WEBHOOK="https://hooks.slack.com/services/..."

# 致命的エラー時に自動送信

注意点 ​

  • 機密情報: エラーログにはAPIキーやファイル内容の一部が含まれる可能性があります。共有時は注意してください
  • ログローテーション: エラーログは自動的にローテーションされますが、定期的に古いログを削除することをお勧めします
  • パフォーマンス: デバッグモードはパフォーマンスに影響します。本番使用時は無効化してください
  • プライバシー: エラーレポートの自動送信を有効にする前に、組織のプライバシーポリシーを確認してください

トラブルシューティング ​

エラーが表示されない場合 ​

bash
# 標準エラー出力が正しくリダイレクトされているか確認
claude 2>&1 | tee claude-output.log

# エラーログファイルの権限確認
ls -la ~/.claude/logs/
chmod 755 ~/.claude/logs/

エラーログの解析 ​

bash
# エラーパターンの抽出
grep "FATAL ERROR" ~/.claude/logs/fatal-errors.log

# 頻度の高いエラーを特定
grep "FATAL ERROR" ~/.claude/logs/fatal-errors.log | \
  awk '{print $4}' | sort | uniq -c | sort -rn

関連情報 ​