Claude Media
「process exited with code N」の対処 — Claude CodeのIDE・SDK連携エラー
Claude CodeTips

「process exited with code N」の対処 — Claude CodeのIDE・SDK連携エラー

VS CodeやAgent SDKアプリが出す「Claude Code process exited with code N」を、終了コード以外の手がかりで切り分ける手順をまとめます。

読了目安 約12分

「Claude Code process exited with code N」は、Claude Code自身が出すエラーではありません。起動した側のプログラム(VS Code拡張やAgent SDKアプリ)が出します。終了コードの数字だけでは何が失敗したかは分かりません。本当の原因はプロセス自身の出力にあります。起動元がそれを捕捉していれば末尾に付き、していなければ起動元のログにしか残りません。

切り分けの中心は番号の解釈ではなく、同じプロジェクトでターミナルからclaudeを直接起動して本物のエラーメッセージを出させることです。例外が1つあります。Windowsでは終了コード4294967295が無害な場合があり、この場合は何も直す必要がありません。

起動元によって、エラーの見え方が変わる

同じ文言でも、手元に残る情報は起動元で違います。VS Code拡張とAgent SDKでは、見るべき場所が別です。

見え方

起動元ごとの見どころ

  • VS Code拡張

    エラーと並んで「View output logs」のリンクが出ます。本物の失敗メッセージはそこにあります。claudeCode.claudeProcessWrapperはclaudeプロセスの起動に使う実行ファイルを指定する設定で、設定している場合はラッパー経由で起動されます。

  • TypeScript SDK

    query()のメッセージをfor awaitで回すループが、通常のErrorで失敗します。メッセージはClaude Code process exited with code 1. stderr: <CLIのstderr末尾>の形で、stderrがあれば末尾に付きます。専用のエラークラスは無く、try/catchで受けます。

  • Python SDK

    文言はCommand failed with exit code 1 (exit code: 1)で、ProcessErrorとして上がり、終了コードは例外のexit_code属性に入ります。Error outputの行は固定文なので、実際のstderrはClaudeAgentOptionsのstderrコールバックで拾います。

Agent SDKでは、CLIが先にエラー結果を報告してから終了した場合に、メッセージが別の形へ置き換わります。Claude Code returned an error result: <CLI自身のエラー報告>です。

コロン以降がCLI自身の報告なので、終了コードより先にそこを読みます。PythonではProcessErrorのサブクラスであるResultErrorとして上がり、data属性に完全なエラー結果が入ります。ResultErrorはProcessErrorのサブクラスなので、except ProcessErrorは両方を捕まえます。区別して扱うならexcept ResultErrorを先に書きます。claude-agent-sdk 0.2.140より前は、エラー結果での終了がResultErrorではなく素のExceptionとして上がっていました。TypeScriptは同じ形のメッセージを持つErrorで失敗します。

ターミナルでclaudeを直接使っているだけなら、このメッセージは見ません。IDE拡張やSDKという中継役が挟まって、はじめて起動元の文言に置き換わります。

切り分けの順番

手順

エラーの正体にたどり着く4手順

  1. 1

    起動元のログを見る

    見る場所は上のカードのとおりです。SDKアプリでは、メッセージを回すループの周りで例外を捕まえておくと、失敗の文面をログに残せます。

  2. 2

    同じプロジェクトで`claude`を直接起動する

    失敗はたいていターミナルでも再現し、今度は本物のエラーメッセージがそのまま表示されます。メッセージが出たら、公式のエラー一覧でその文言を引きます。

  3. 3

    `claude doctor`で土台を確認する

    起動できない状態でも、シェルから実行できます。インストール・設定ファイル・Remote Controlの利用可否が出ます。

  4. 4

    `--debug-file`でログを手元に残す

    再現はするが手がかりが薄いときに使います。起動時の動きがファイルに残ります。

cd /path/to/your/project
claude

Windowsで出る終了コード4294967295は、無害なことがある

Windowsのネイティブ版は、ターンが終わった直後に終了コード4294967295で終了することがあります。メッセージの待ちがなく、バックグラウンドタスクも動いていないターン境界でこの終了が起きた場合、VS Code拡張はエラーを出しません。セッションを静かに閉じるだけで、次にメッセージを送れば会話は再開されます。

v2.1.273より前のバージョンでは、このターン境界の終了でもエラーを出していました。失われたものは何もありません。古いバージョンの拡張で、応答が終わった直後に毎回このエラーを見るなら、まずバージョンを確認する価値があります。

claude doctorは何を出すか

claude doctorはセッションを開始せずに診断を出力します。--helpの説明では、現在のディレクトリの設定ファイルを信頼確認なしで読み、修復まで行いたいときはセッション内の/doctorを使う、とされています。つまりclaude doctorは診断だけで、修復はしません。

v2.1.287で、空のHOMEと空の設定ディレクトリを指定して実行すると、先頭は次のようになりました(パスは一部省略)。

Claude Code doctor
 
Running: native (2.1.287)
Platform: darwin-arm64
Path: ~/.local/share/claude/versions/2.1.287
Config install method: not set
Search: OK (bundled)
Auto-updates: enabled
Auto-update channel: latest
 
Remote Control
Remote Control requires a claude.ai subscription.
- Not signed in to claude.ai

どの実行ファイルが動いているか、インストール方法、検索(ripgrep)の状態、自動更新の有無が1画面で分かります。IDEから起動したclaudeと、自分のシェルで動くclaudeが別物ではないか(別のバージョン、別のパス)を疑うときの材料になります。ログインしていない環境でも実行でき、未ログインの場合はRemote Controlの欄にNot signed in to claude.aiと出ます。

--debug-fileで出力を手元に残す

ターミナルで再現しても手がかりが薄いなら、--debug-file <path>で出力先のファイルを指定します。--helpでは「ファイルパスを指定してデバッグログを書く。デバッグモードも暗黙に有効になる」と説明されています。--debugは[filter]を取れるので、"api,hooks"のようにカテゴリで絞ることもできます。絞り込みが効くのは=で値をつなぐ書き方だけです。claude --debug='mcp,startup'と書きます。空白で区切ると、絞り込みなしのデバッグモードになります。

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

環境変数CLAUDE_CODE_DEBUG_LOGS_DIRでログの置き場所を決めている環境でも、--debug-fileの指定が優先されます。Claude Codeのセッション内からは/debugでも実行時の問題を診断できます。

同じ「起動元のエラー」でも原因の層が違う

起動元のプログラムが出すエラーは、公式のエラー一覧で「Wrapper and IDE errors」にまとまっています。process exitedと取り違えやすいものは、次の2つです。

エラー状況次の一手
Could not locate the Claude CLI on PATH状況WindowsのVS Code統合ターミナルがPowerShellで、拡張がclaudeを見つけられない次の一手where.exe claudeでPATHを確認する
The connection to Claude Code ended before this message completed状況拡張がメッセージを送ったが、claudeプロセスが確認や完了の前に接続を閉じた次の一手同じメッセージをもう一度送る。繰り返すならターミナルで再現させる

前者は、起動はしたが失敗した、という話ではありません。PowerShellでPATH上の名前からclaudeを起動すると、開いているフォルダのclaudeが実行されかねないため、拡張が起動を拒否する仕組みです。対処は3つあります。

  • VS Codeの外で新しいPowerShellを開き、where.exe claudeを実行する。パスが出なければインストールディレクトリをPATHに追加する。パスが出るなら、PowerShellプロファイル由来か、VS Codeがまだ拾っていないPATH変更が原因
  • PATHはプロファイルではなく、ユーザーまたはシステムの環境変数に設定する。拡張はプロファイルを実行しないため、プロファイルだけに書いた変更は届かない
  • PATHを変えたらVS Codeを再起動する。拡張は起動時に捕まえたPATHしか見ない

後者は、拡張が「処理されたか分からない」ため再送を求めるメッセージです。process exitedのように終了コードは付かず、次のメッセージで新しいclaudeプロセスが会話を再開します。

終了コードが付かない起動失敗は、別のメッセージで出る

claudeの実行ファイルが見つかったのに起動できない場合、SDKは「終了コード付きの終了」とは別のメッセージを出します。検索語が変わるので、文面を見てどちらの話かを先に分けます。

  • Python SDKはCLIConnectionErrorで、本文はFailed to start Claude Code:に続けてOS自身のエラーです
  • TypeScript SDKは、実行ファイルのパスを添えたexists but failed to launchか、それ以外のFailed to spawn Claude Code processです。どちらも専用のエラークラスは持たないErrorです

多くの場合、指定したパスがテキストファイルやディレクトリ、実行権限のないファイルを指しています。cli_path(Python)やpathToClaudeCodeExecutable(TypeScript)を指定していないなら、設定を外してSDKに探させるのが近道です。

WindowsのPython SDKには固有の落とし穴もあります。cli_pathが.batや.cmdのとき、npmが作るclaude.cmdも含めて、Refusing to execute batch scriptで接続を拒否します。cmd.exe経由だと引数に紛れた命令を実行されかねず、確実なエスケープ手段が無いためです。ネイティブのclaude.exeを指すか、cli_pathを外します。

VS Code拡張が使うclaudeは、拡張に同梱された専用のコピーです。拡張を入れても、シェルのPATHにclaudeは入りません。ターミナルでclaudeと打って切り分けるなら、スタンドアロン版のインストールが別途要ります。

拡張のビルドにお使いのプラットフォーム向けのバイナリが同梱されていないと、有効化の時点でUnsupported platformが出ます。その場合は、別途入れたclaudeをclaudeCode.claudeProcessWrapperで指します。バイナリが同梱されているビルドでは、そのパスが引数として渡されます。

SDKアプリを自作しているときのログの置き方

SDKはclaudeを子プロセスとして起動します。呼び出し側がその標準エラー出力を捨てていると、手元に残るのは終了コードだけです。stderrをアプリ自身のログに書いておくと、次に同じエラーが出たときアプリのログだけで原因を追えます。

シグナルで止められた場合は、Claude Code process terminated by signal <name>という同じ形のメッセージになります。終了コードの代わりにシグナル名が入るので、process exited with codeとは別の検索語で調べることになります。

Pythonでstderrを拾う最小の形は、次のとおりです。コールバックは文字列を1つ受け取る関数で、ClaudeAgentOptionsのstderrに渡します。TypeScriptも、オプションのstderrに(data: string) => voidを渡す同じ形です。

import logging
from claude_agent_sdk import ClaudeAgentOptions
 
options = ClaudeAgentOptions(
    stderr=lambda line: logging.error("claude stderr: %s", line),
)

SDKのバージョンによっては、起動に失敗した理由が結果メッセージとして返ることもあります。TypeScript SDKはv0.3.274以降で、既知の起動失敗の際に、stderrと同じ文面をerrors配列に入れたerror_during_executionの結果を書いてから終了します。環境変数CLAUDE_CODE_STARTUP_FAILURE_RESULTSを1にすると、すべての起動失敗理由でこの結果が返ります。

よくあるつまずき

  • VS Codeやサービス管理のプロセスのようなGUI・常駐プロセス経由の起動は、ログインシェルのプロファイルで設定したPATHを引き継がないことがあります。ターミナルでは動くのにIDE経由だけ失敗するなら、この環境差を疑います。Agent SDKの公式トラブルシューティングも、IDEやサービスマネージャーから起動したプロセスはPATHが異なることが多いと説明しています。SDKアプリからclaudeが見つからないときは、アプリが動くのと同じ環境でclaude --versionが通るかを確認します
  • どうしても原因が分からなければ、セッション内から/feedbackで報告するか、GitHubリポジトリで既知のissueを探します。issueには、完全なエラー文とバージョン(SDKならSDKのバージョン)を添えます

まとめ

起動元のログに本物のエラー文が残っていれば、そこから公式のエラー一覧を引けます。文が残っていなければ、ターミナルでの直接起動と--debug-fileに進みます。

この記事を共有:XはてブLinkedIn

関連する記事

Claude Code をもっと見る →