--debug-file（デバッグファイル）

Claude Code が突然エラーで落ちる・固まる・MCPが繋がらない等の不具合に遭って、ログを取って原因を絞り込みたい人向け

Claude Code が突然エラーで落ちる、応答が固まる、繋いだはずのMCPサーバーが返事をしない。こういう不具合に遭った時、原因を絞り込む手がかりは「裏で何が起きていたか」のログです。--debug-file は、その裏側の動きを指定したファイルに書き出すためのスイッチです。

付けて起動するだけで debug モードが自動でオンになり、ログが指定先に流れていきます。標準エラーに垂れ流す --debug 単体版と違って、後から落ち着いて中身を読み返せるのが強みです。

噛み砕くと

家電の不具合を直す時、症状を電話口で伝えるのと、動作中の様子を録画して送るのとでは情報量が全然違います。--debug-file は後者に近い発想です。Claude Code の中で何が起きていたかを、画面に流れて消える文字列ではなく、後から見返せるノートに残す動作だと考えると分かりやすいです。

普段は使わなくていいです。困った時に開ける「録画モード」だと思っておけば十分です。

大事な前提：ファイルの保存先を一つ自分で決めて渡す

このスイッチは、後ろにファイルの保存先を一つ書き足す必要があります。書き足さずに --debug-file だけ叩いてもエラーになります。公式の例では /tmp/claude-debug.log が使われています。これは「パソコンの一時保存フォルダの中に claude-debug.log という名前で残す」という意味の書き方です。

もう一つ大事な点として、debug モードを別途オンにする必要はありません。--debug-file を渡した時点でdebug モードは自動で有効になります。公式ドキュメントには「Implicitly enables debug mode」と明記されています。

「MCPサーバーが起動時に繋がらない」場面で、実際に手を動かす

MCP は外部ツールを Claude Code に繋ぐ仕組みです。設定したのに、起動するたびに「サーバーが見つかりません」みたいなメッセージが出る。よくある詰まりです。これを --debug-file で原因を絞り込む流れを書きます。

ステップ1: 保存先のファイル名を決める

まずログをどこに残すかを決めます。今回は分かりやすく自分のホームフォルダ直下に claude-mcp.log という名前で残します。

~/claude-mcp.log

~ はホームフォルダの省略記号です。Macなら /Users/自分の名前、Linuxなら /home/自分の名前 に該当します。最初にこれに決めておくと、後でファイルを開く時に迷いません。

ステップ2: --debug-file を付けて Claude Code を起動する

ターミナルで以下を叩きます。

$ claude --debug-file ~/claude-mcp.log

普段の claude だけと違って、後ろにスイッチが2つ並んでます。--debug-file がスイッチ名、~/claude-mcp.log が「どこに書き出すか」の答えです。

ステップ3: 山カッコは打たない

公式ドキュメントには --debug-file <path> と書かれていますが、この < と > は実際には打ちません。「ここにファイルの場所を入れてね」というプレースホルダー記号です。

初心者がやりがちな勘違いに、claude --debug-file <~/claude-mcp.log> のように山カッコをそのまま打ってしまうケースがあります。これは動きません。山カッコ無しで素のまま書きます。

ステップ4: 起動を見届ける

Enter を押すと、いつもの Claude Code の対話画面が立ち上がります。見た目はほぼ変わりません。でも裏では debug モードが自動でオンになっていて、起動時の動き・MCP サーバーへの接続試行・タイムアウトの様子が、指定したファイルに書き込まれていきます。

ステップ5: 別のターミナルでログを覗く

Claude Code を起動したままにして、もう一つターミナルを開きます。そこで以下を叩くと、ログが流れていく様子をリアルタイムに見られます。

$ tail -f ~/claude-mcp.log

tail -f は「ファイルの末尾を、追記されるたびに表示し続ける」コマンドです。MCP サーバーが繋がろうとして失敗してる瞬間が、ここに出てきます。

ステップ6: 原因のキーワードを探す

ログの中に mcp や error や timeout といった単語が並びます。「サーバーへの接続が10秒で打ち切られた」「指定したコマンドが見つからない」みたいな手がかりが見つかるはずです。あとはその情報を頼りに、設定ファイルを直すか、サーバー側のコマンドを直すかを判断します。

つまり --debug-file は何をしてくれるのか

• やってくれる：指定したファイルに debug ログを書き出す。debug モードも自動でオンになる。後から落ち着いて原因を読み返せる
• やってくれる：debug ログの保存フォルダを指定する設定値 CLAUDE_CODE_DEBUG_LOGS_DIR が先に決まっていても、--debug-file の方を優先する。一時的に別の場所に出したい時に上書きできる
• やってくれない：ログの中身を要約したり、エラーの原因を教えてくれたりはしない。出てくるのはあくまで生のログ。読み解くのは自分
• 意味が薄い場面：Claude Code が安定して動いている平常時。録画モードを常時オンにしていてもファイルが膨らむだけで得がない

使いどころ3シナリオ（具体題材で再現）

シナリオ1: MCPサーバーが起動時に繋がらない時

SQLite を扱う MCP サーバーを設定したのに、Claude Code 起動のたびに「server not found」と出る。claude --debug-file ~/mcp-debug.log で起動し、別ターミナルで tail -f ~/mcp-debug.log を流しっぱなしにすると、接続時にどのコマンドを叩いていて、どこで失敗してるかが行単位で見えます。「指定したサーバーの実行ファイルが見つからない」「読み込み権限がない」「タイムアウト10秒で諦めた」あたりが手がかりになります。

シナリオ2: 長時間セッションで応答が固まる時

30分以上 Claude Code と対話していたら、急にスピナーが回ったまま戻ってこない。再起動はできるけど、また同じ症状が出ると面倒です。claude --debug-file ~/claude-hang.log で起動して、固まる瞬間を待つ。固まった後に別ターミナルで tail -100 ~/claude-hang.log を見ると、最後にどの処理で止まったかが分かります。API呼び出しの返事待ちか、ファイル読み込みか、ツール実行のどれかに当たりが付きます。再現条件が掴めれば回避策を打てます。

シナリオ3: 出先のチームに不具合の状況を共有したい時

自分の環境で起きてる不具合を、リモートで作業中の同僚や OSS の開発者に伝えたい場面。「なんか動かない」では話が進まないので、claude --debug-file /tmp/claude-debug.log で再現させて、出来上がったログファイルを zip にして渡します。相手は手元に同じファイルが来るので、生の動作ログを見ながら原因を考えられます。再現条件と一緒に渡すと話が早いです。

初心者が踏みやすい落とし穴

• 山カッコをそのまま打ってしまう。公式ドキュメントの --debug-file <path> の < > は「ここにファイルの場所を入れてね」という記号で、実際には打たない。claude --debug-file ~/debug.log のように素のまま書く
• ファイル名を渡し忘れる。claude --debug-file だけ叩いてもエラーになる。後ろに必ずファイルの保存先を一つ書き足す
• --debug を別途付けようとする。--debug-file は debug モードを自動でオンにするので、claude --debug --debug-file ~/x.log のように両方付ける必要はない。片方で十分
• 書き込めない場所を指定する。読み込み専用のフォルダや、自分に書き込み権限がない場所を渡すと、ログが残らない。最初は /tmp や自分のホームフォルダなど、確実に書き込める場所から試すのが安全
• ログを常時オンで使い続ける。何も問題が起きていない時に --debug-file を毎回付けると、ファイルがどんどん膨らむ。困った時だけ使うのが基本
• CLAUDE_CODE_DEBUG_LOGS_DIR と併用して混乱する。両方設定されている時は --debug-file が勝つ。「設定値で ~/logs/ に出してたはずなのに /tmp/ に出てる」みたいに見えたら、起動コマンドに --debug-file が付いていないか確認する
• ログを読まずに眺めて終わる。出てくるのは生のログで、自動で要約はされない。error timeout failed mcp といったキーワードで grep をかけて、当たりを付けるのが現実的

書き方

claude --debug-file ファイルの保存先

やってみるとこうなる

入力

claude --debug-file /tmp/claude-debug.log

出力例

（見た目は通常の Claude Code 対話画面が立ち上がる。裏では指定したファイルに debug ログが書き出される）

別ターミナルで tail -f /tmp/claude-debug.log を流すと、以下のようなログが追記されていく：

[mcp] connecting to server: sqlite
[mcp] command: /usr/local/bin/sqlite-mcp-server
[mcp] timeout after 10000ms
[mcp] error: server not responding
[hooks] PreToolUse triggered
[api] request sent, awaiting response
...

関連項目

• /debug（デバッグ）
• MCP（エムシーピー）
• /claude-cli（準備中）
• /permissions（パーミッションズ）
• --verbose（ヴァーボース）

公式ドキュメント

https://code.claude.com/docs/en/cli-reference