「process exited with code N」の対処 — Claude CodeのIDE・SDK連携エラー
VS CodeやAgent SDKアプリが出す「Claude Code process exited with code N」を、終了コード以外の手がかりで切り分ける手順をまとめます。
「Claude Code process exited with code N」は、Claude Code自身ではなく、それを起動した側のプログラム(VS Code拡張やAgent SDKアプリ)が出すエラーです。終了コードの数字だけでは何が失敗したかは分かりません。本当の原因はプロセス自身の出力側にあり、起動元がその出力を捕捉していれば付け足され、捕捉していなければログにしか残りません。切り分けの中心は、番号を読み解くことではなく、同じプロジェクトでターミナルから直接claudeを起動して本物のエラーメッセージを再現させることです。
「process exited with code N」の意味
このエラーは、VS Code拡張やAgent SDKアプリのように、Claude Codeを自分のプロセスとして起動する側のプログラムから出ます。配下のclaudeプロセスが0以外の終了コードで終わったことだけを伝えるメッセージで、Nの部分に実際のコードが入ります。
Error: Claude Code process exited with code 1公式のトラブルシューティングガイドは、このメッセージを「VS CodeまたはSDKアプリ内で見る」エラーとして明示的に分類しています。逆に言えば、ターミナルでclaudeを直接起動して使っているだけなら、このメッセージ自体を見ることはありません。IDE拡張やSDKアプリという中継役が挟まることで、はじめて起動元プログラム独自の文言に置き換わるという構造です。
公式が示す3つの切り分け手順
原因を特定する具体的な方法は3つあります。
- VS Codeなら「View output logs」リンクをたどる。エラーと一緒に表示されるリンクから、本来の失敗メッセージを含む出力ログを開けます
- 同じプロジェクトのターミナルで
claudeを直接起動する。失敗はたいていそこでも再現し、今度は本物のエラーメッセージが画面にそのまま表示されます claude doctorでインストールと設定を確認する。ターミナルからセッションを開始せずに読み取り専用の診断を出力するコマンドで、インストールの健全性・設定ファイルの検証エラー・Remote Controlの利用可否まで確認できます
cd /path/to/your/project
claudeclaude doctorターミナルでの再現がもっとも確実な理由は単純です。ラッパー側のログに出力が捕捉されるとは限らない一方、ターミナルで直接起動すれば、失敗の瞬間のメッセージがそのまま画面に出るためです。
似たIDE・ラッパー系エラーとの見分け方
同じ「起動元のプログラムから出るエラー」というカテゴリに、もう1つ別のエラーがあります。文言が違うので混同はしにくいですが、原因の層は近い位置にあります。
| エラー | 発生元 | 原因の性質 |
|---|---|---|
| Claude Code process exited with code N | 発生元VS Code拡張 / Agent SDKアプリ | 原因の性質配下のclaudeプロセスが0以外の終了コードで終了した。番号自体は原因を語らない |
| Could not locate the Claude CLI on PATH | 発生元VS Code拡張(Windows・PowerShell限定) | 原因の性質インストール済みのclaude実行ファイルがPATH上で見つからず、拡張が起動自体をブロックした |
後者はWindowsでVS Codeの統合ターミナルを開き、そのシェルがPowerShellのときに限定して出ます。claudeをPATH上の名前で起動すると、開いているフォルダのclaudeが実行されてしまう危険があるため、拡張が起動を拒否する仕組みです。前者のように「起動はしたが失敗した」のではなく、「起動そのものをブロックした」点が違います。
「Could not locate the Claude CLI on PATH」に当たった場合の対処は別の3手順です。①VS Codeの外で新しいPowerShellウィンドウを開きwhere.exe claudeを実行する。パスが出なければインストールディレクトリをPATHに追加します。パスが出るならPowerShellプロファイル経由か、VS Codeがまだ拾えていないPATH変更のどちらかです ②PATHの設定はPowerShellプロファイルではなく、ユーザーまたはシステムの環境変数として設定する。拡張機能はプロファイルを実行しないため、プロファイルだけに書いたPATH変更は届きません ③PATHを変更した後はVS Codeを再起動する。拡張は起動時に取り込んだPATHしか見ないため、変更は再起動して初めて反映されます。
claude --debugで出力を捕まえる
ターミナルで再現させても手がかりが薄いと感じたら、デバッグモードを使います。--debugはカテゴリでフィルタしたデバッグログを有効にし、--debug-file <path>を使うと出力先を指定のファイルに固定できます。起動そのものが失敗している(プロセスがすぐ終了する)場合は、カテゴリを絞らず--debug単体で起動し、初期化まわりのログをまとめて出力させたほうが取りこぼしがありません。
claude --debug-file /tmp/claude-debug.logこのログには、通常の画面出力よりも詳しい起動時の情報が残ります。IDEやSDKアプリのログにClaude Codeプロセスの出力が捕捉されていない場合でも、ターミナルから--debug-file付きで再現させれば、原因の手がかりを自分の手元に残せます。
それでも解決しない場合のエスカレーション手順
ターミナルでの再現・claude doctor・デバッグログのいずれでも原因が特定できないときは、次の順で対応します。
- GitHubリポジトリのissueで既知の不具合を検索する。無ければ、OS・実行したインストールコマンド・完全なエラー出力を添えて新規issueを作成する
claude --versionは動くのに別の場所で問題が起きている場合は、claude doctorで自動診断レポートを取得する- セッションを開始できる状態であれば、セッション内から
/feedbackで問題を報告する
VS CodeとAgent SDKでの見え方の違い
VS Code拡張では、エラーと一緒に「View output logs」というリンクが表示されるため、まずそこをたどるのが最短です。拡張が独自のclaudeProcessWrapper設定でバイナリの起動方法をカスタマイズしている場合は、その設定が指す実行ファイルが正しく動くかどうかも切り分けの対象に含めます。
Agent SDKアプリでは、こうしたリンクは無く、アプリ自身のログにClaude Codeプロセスの出力が残っているかどうかに依存します。SDKは配下のclaudeプロセスを子プロセスとして起動するため、呼び出し側の実装が子プロセスの標準出力・標準エラーを収集せずに破棄していると、終了コードの番号しか手元に残りません。自分でSDKアプリを実装している場合は、子プロセスの出力を自前のログファイルへ書き出すようにしておくと、次に同じエラーが起きたときアプリ側のログだけで原因が追えるようになります。
よくあるつまずき
- VS CodeやSDKホストのようなGUI・常駐プロセス経由で起動したプログラムは、ログインシェルのプロファイル(
PATHや環境変数)を必ずしも引き継ぎません。ターミナルでは動くのにIDE経由だけ失敗する場合は、まずこの環境差を疑います。これはClaude Code固有の挙動ではなく、サブプロセスを起動するアプリ全般に共通する一般的な注意点です claude doctorは読み取り専用の診断であり、問題を自動修正しません。セッション内で修正まで行いたい場合は/doctorを使います- 公式ドキュメントが示している具体的な終了コードの例は
1のみです。他の番号について「このコードならこの原因」と断定した情報は無いため、番号から原因を決めつけずに出力の中身を確認します --debug-fileで残したログをissueに貼る前に、APIキーやプロジェクトパスなど手元固有の文字列が含まれていないか一度目を通しておくと、共有時のやり直しを防げます
よくある質問
終了コードの数字から原因を特定できますか
できません。公式ドキュメントは終了コード単体では原因を特定できないと明記しており、本当の原因はプロセス自身の出力側にあります。番号を手がかりにするより、ターミナルでの再現やログの確認を優先します。
ターミナルでclaudeを直接使っている場合もこのエラーは出ますか
出ません。「Claude Code process exited with code N」は、VS Code拡張やAgent SDKアプリのようにClaude Codeを自分のプロセスとして起動する側が出すメッセージです。ターミナルで直接起動している場合は、失敗そのものが画面に直接表示されます。
claude doctorを実行しても手がかりが無い場合はどうすればよいですか
claude doctorはインストールと設定の健全性を確認するものなので、実行時エラーの原因まではすべて拾えません。次はターミナルでの再現を試し、それでも再現しない場合はIDE拡張やSDKアプリ側のログ設定を見直し、Claude Codeプロセスの標準出力・標準エラーを捕捉する設定になっているか確認します。
GitHub issueを作るときに何を書けば調査してもらいやすいですか
OS、実行したインストールコマンド、そして完全なエラー出力の3点が最低限必要です。「process exited with code」というメッセージだけでは調査する側も原因を特定できないため、ターミナルで再現させた本物のエラーメッセージか、--debug-fileで残したログの該当箇所を添えるようにします。
まとめ
「process exited with code N」は、Claude Code自身の障害内容を直接教えてくれるメッセージではありません。VS Codeなら「View output logs」、それが無ければ同じプロジェクトでターミナルからclaudeを直接起動し、本物のエラーメッセージを画面に出させるのが最短です。claude doctorはインストールと設定の健全性を確認する補助として使い、それでも足りなければ--debug-fileでログを残します。番号だけを見て原因を決めつけないことが、遠回りを避ける一番のコツです。