plugin_marketplacesでバイナリが配置されない原因と対処 — claude-code-action

plugin_marketplacesで何が起きるか

anthropics/claude-code-action@v1にplugin_marketplacesを設定したGitHub Actionsワークフローが、claude installのログでは成功表示なのに、その直後のマーケットプレース追加でENOENTエラーになる既知の問題があります。ログには次のように表示されます。

⚠ Setup notes:
  ● installMethod is native, but directory /home/runner/.local/bin does not exist
  ● installMethod is native, but claude command not found at /home/runner/.local/bin/claude
 
✔ Claude Code successfully installed!
  Version: 2.1.129
  Location: ~/.local/bin/claude

successfully installedと表示された直後に、次のエラーで停止します。

Action failed with error: Failed to add marketplace '...': ENOENT: no such file or directory, posix_spawn '/home/runner/.local/bin/claude'

インストーラーは警告を出しながらも終了コード0を返し、続く✔ Claude Code successfully installed!の表示は、実際にはバイナリが配置されていない状態のまま出ています。issueの起票者はこれを「ログの表示自体が誤解を招く(misleading)」と説明しています。

8月の再発報告では、警告の文面が変わっています。claude command at /home/runner/.local/bin/claude missing or brokenという書き方になり、Version:の行は消えてLocation:だけが残りました。見るべき手がかりは文面ではなく、Setup notesの警告とsuccessfully installedが同じログに並ぶことです。

原因はインストーラー側とaction側の両方にある

原因は1つの不具合ではなく、2つの見落としが重なって表面化します。

action側の実装は公開されているソースで追えます。src/entrypoints/run.tsのinstallClaudeCode()は、Claude Codeのバージョンを文字列で固定し、次のコマンドを最大3回まで試します。

set -o pipefail; curl -fsSL https://claude.ai/install.sh | bash -s -- <version>

失敗時の再試行(5秒待って再実行)が動くのは、このコマンドが非ゼロで終わったときだけです。終了コード0で終わる今回の症状は、再試行の手前で「成功」と判定されます。成功後の処理もパスを組み立てて返すだけで、existsSync()のようなバイナリの存在確認は入っていません。

インストールスクリプト側も同じ構造です。install.shは最新版のバイナリをいったんダウンロードし、そのバイナリのinstallサブコマンドにstable・latest・バージョン番号のいずれかを渡して配置を任せます。配置に失敗して非ゼロで終われば、スクリプトも同じコードで終了します。今回の症状では、この配置処理が警告だけで0を返しています。

この2つ目の問題はplugin_marketplaces固有ではありません。コメント欄では、plugin_marketplacesもpluginsも設定しないワークフローでも同じ警告ログが出ることが報告されています。この場合マーケットプレースの処理自体はスキップされるため、失敗するタイミングが後ろにずれ、SDK起動時に次のエラーとして表面化します。

SDK execution error: ReferenceError: Claude Code native binary not found at /home/runner/.local/bin/claude.
Please ensure Claude Code is installed via native installer or
specify a valid path with options.pathToClaudeCodeExecutable.

つまりplugin_marketplacesを外すだけの対処は、失敗する場所をaddMarketplace()からSDK実行時へ移すだけで、根本原因(バイナリが実際には配置されていない)は解消していません。プロンプト実行だけのシンプルな構成でも、SDK経由でClaude Codeを起動する限り同じ地雷を踏みます。GitHub Actions組み込みの基本構成そのものはClaude CodeをGitHub Actionsに組み込むにまとめています。

表面化から現在までの経緯

この不具合は一度きりの発生ではなく、複数のタイミングで再発が報告されています。

5月6日の「解決したようだ」というコメントは主観的な観察で、修正の告知ではありません。

ランナーイメージは5月が20260413.86.1、8月が20260816.277.1で、どちらもubuntu-24.04です。イメージが違っても出ているので、特定のイメージの問題とは言えません。5月の別のコメントには、regression前のactionのコミット(2cc1ac1、v1.0.112)へピン留めして凌いだという報告もあります。

自分のワークフローが該当するかを見分ける

症状は構成によって2通りに出ます。次の順で見ると、切り分けに迷いません。

- name: Inspect install location
  if: failure()
  run: |
    ls -la ~/.local/bin ~/.local/share/claude 2>&1 || true

~/.local/binが存在しないか、claudeが無ければ、この記事の症状です。ローカル環境でnpmインストール時に出るnative binary not installedは原因が異なり、native binary not installedエラーの原因と対処で扱っています。

報告されている範囲

コメント欄の報告のうち、ランナーが書かれている報告は、いずれもGitHub-hostedのubuntu-24.04かubuntu-latestです。複数の無関係なリポジトリにまたがっています。認証方式はclaude_code_oauth_tokenによるOAuth認証と、明記のない構成の両方が含まれ、認証方式による違いは報告されていません。issueのスレッドには、セルフホストランナーやmacOS・Windowsランナーでの再現報告はありません。GitHub-hosted Ubuntu以外で同じ症状が出るかどうかは、スレッドからは判断できません。

今すぐ使える回避策

修正の取り込みを待たずに使える回避策は2つあります。

1. ~/.local/binを事前に作成する

actionを実行するステップより前に、ディレクトリを作成しておく方法です。

- name: Create Claude Code install directory
  run: mkdir -p ~/.local/bin
 
- name: Run Claude Code
  uses: anthropics/claude-code-action@v1

配置先が存在している状態にすれば、インストーラーはバイナリを正常に配置できます。5月のコメントでは、この方法でv2.1.129のインストーラーが配置に成功したと報告されています。ただしこれは、ディレクトリの欠落以外の理由で失敗するケースまではカバーしない、コミュニティ発の暫定対応です。

2. 事前インストールしたバイナリをpath_to_claude_code_executableで指定する

action.ymlで定義されているpath_to_claude_code_executableは、カスタムのClaude Code実行ファイルを指定すると自動インストールをスキップする入力です。run.tsのinstallClaudeCode()も、この環境変数があればインストールを丸ごと飛ばします。指定されたパスのディレクトリをPATHに足して、そのパスを返す動きです。

インストール手順にはバージョンを指定する方法があり、curl -fsSL https://claude.ai/install.sh | bash -s 2.1.89のように書きます。この2つを組み合わせると、action自身のインストール処理を経由せずに済みます。

- name: Install a pinned Claude Code version
  run: |
    mkdir -p ~/.local/bin
    curl -fsSL https://claude.ai/install.sh | bash -s 2.1.289
    test -x ~/.local/bin/claude
 
- uses: anthropics/claude-code-action@v1
  with:
    path_to_claude_code_executable: /home/runner/.local/bin/claude
    claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}

2.1.289は、v1タグのrun.tsが指定しているバージョンの値です。この値はrun.tsの更新に合わせて変わるため、最新の値はそちらで見られます。特定のバージョンを勧めるものではなく、actionが想定している版にそろえる例として置いています。

mkdir -pとtest -xを残している理由は2つあります。1つは、install.shがバージョンを指定しても最新版のバイナリを先にダウンロードし、そのインストーラーに配置を任せる構造だからです。バージョンを固定しても、配置処理は最新のインストーラーが行います。

もう1つは、path_to_claude_code_executableに渡したパスをactionが存在確認しないからです。修正PR #1754の説明も、カスタムの実行ファイルに存在確認を足す変更を含んでいます。存在確認を省くと、パスだけが存在しないファイルを指し、この不具合と同じ、エラーを出さないまま失敗する状態を自分で作ることになります。

構成別の影響

同じ不具合でも、ワークフローの構成によって症状の出方と回避のしやすさが変わります。

修正PRは2件とも取り込まれていない

この不具合に対する修正の提案は2回出ていますが、いずれもmergeされていません。

• PR #1346: installClaudeCode()にバイナリの存在確認を追加する内容です。
• PR #1754: 同様にexistsSync()で確認を加え、失敗時のエラーメッセージでpath_to_claude_code_executableの利用を案内する内容です。

issue #1290自体はクローズされておらず、追跡は続いています。

2件とも「インストーラーの終了コードを信頼せず、返す前にバイナリの実在を確認する」という同じ方向の修正です。1回目のクローズから3か月後に、5月の報告とは別の経路(2.1.243と2.1.241というバージョン差)で再発が出ています。この問題は、action単体の一度きりの不具合ではなく、ネイティブインストーラーのリリースごとに繰り返し起こりうる構造だという見方と整合します。issueのコメントでも、install.shが最新版を引くことが原因ではないかという仮説が出ています。

よくあるつまずき

• plugin_marketplacesを外して直ったように見えても、native binary not found のログが無いか確認します。このエラー文字列が出ていれば、addMarketplace()からSDK起動時へ失敗箇所が移動しただけの可能性があります
• actionをSHAで固定すると、Claude Codeのバージョンも一緒に固定されます。インストールするバージョンはrun.tsに文字列で書かれており、actionの更新コミットごとに書き換わります。タグ@v1のまま使う場合は、actionの更新がClaude Codeのバージョン変更を連れてくる点に注意します
• SHA固定でも、インストーラーの挙動は固定されません。install.shは最新版のバイナリを先に取得するため、同じバージョンを指定しても配置処理は新しいインストーラーに依存します
• mkdir -p ~/.local/binはランナーごとの暫定対応です。GitHub-hosted runnerは実行のたびに使い捨てられるため、この回避策はワークフロー内の該当ステップに毎回含める必要があります
• path_to_claude_code_executableを指定しているのにエラーが出る場合は、指定したパスにバイナリが実際に存在するかをランナー上で調べます。事前インストールのステップが別のジョブ・別のランナーで実行されていると、パスだけ渡してもファイルは存在しません
• 失敗時のCIログは読みにくくなります。SDK実行エラーの直前に、圧縮されたバンドルのソースが数KB分そのままログへ出力されるという報告があります。本来のエラーメッセージは、ログの末尾側から遡ると見つけやすくなります

手元のインストーラーの引数

v2.1.289でclaude install --helpを実行すると、次のとおりです。ワークフローで使うinstall.shの引数と同じく、stable・latest・具体的なバージョンを受け取ります。

Usage: claude install [options] [target]
 
Install Claude Code native build. Use [target] to specify version (stable,
latest, or specific version)
 
Options:
  --force     Force installation even if already installed
  -h, --help  Display help for command

ヘルプに配置先を指定するオプションは載っていません。セットアップのページは、macOS・Linuxの配置先を~/.local/bin/claudeと書いています。ワークフローから効かせられる手段は、ランナー側でそのディレクトリを用意しておくことです。

まとめ

plugin_marketplaces設定時に起きる「claude installは成功表示なのにバイナリが配置されない」問題は、インストーラーが警告付きで終了コード0を返すことと、actionがその終了コードだけで成功と判定することが重なって起きます。修正PRが取り込まれるまでは、~/.local/binの事前作成か、事前インストールしたバイナリのpath_to_claude_code_executable指定が回避策になります。plugin_marketplacesを使い続けるなら、手軽なmkdir -pで足ります。バージョンやインストーラーの挙動の揺れまで避けたいなら、事前インストールとpath_to_claude_code_executableの組み合わせです。どちらでもtest -xでバイナリの実在を調べるステップを自分で足すと、気づかないうちに失敗する事態は避けられます。

GitHub Actions上で似た症状に遭遇した別の不具合として、allowed_non_write_users設定時にBashコマンドが全滅する問題がClaude Code v2.1.227で修正されています。