Claude Codeのロックファイル残留でインストール失敗する原因と直し方

Claude Codeのインストールがロックファイルで失敗する

Claude Codeのインストールやアップデートが次のメッセージで止まる場合、原因は前回のインストール試行が残した古いロックファイルです。

Could not install - another process is currently installing Claude. Please try
again in a moment.
 
Try running with --force to override checks

さらにやっかいなのは、GitHub Actions(anthropics/claude-code-action)上でこのエラーが起きると、ワークフローのログには✅ Installation complete!と成功したかのように表示される点です。実際にはclaudeバイナリがPATHに存在せず、直後の実行ステップがerror: Executable not found in $PATH: "claude"で落ちます。最初の報告時点の環境はubuntu-latestランナー・Action v1.0.21・Claude Code 2.0.50でした。後続のコメントでは異なるバージョンの組み合わせでも同じ症状が確認されており、特定のバージョン限定の不具合ではありません。claude-code-actionのGitHub issue #709で2025年11月29日に報告されました。それ以降、macOS・Ubuntu・Fedora・Windowsの各環境から同じ症状の報告が続いています。

なぜ古いロックファイルが残るのか

インストール処理は多重実行を防ぐため、作業中はロックファイルを作成し、完了時に削除します。issue #709の報告で起きていたのは、次の2段階です。

issue内では、恒久対応の方向性として①リトライ前のロックファイル削除、②リトライ時の--force自動付与、③インストール完了報告前にバイナリの実在確認、④タイムアウト値の見直し、の4点が提案されています。

このissueの直前に、インストール処理への改善が2件マージされています。2025年11月22日のPR #694は、2分のタイムアウトと最大3回のリトライを追加しました。11月25日のPR #700は、timeoutコマンドがmacOSに無い問題へのクロスプラットフォーム対応です。issue #709はその4日後の11月29日に報告されています。

つまりリトライの仕組みは既にあり、それでも直らなかったことになります。改善案の①がリトライ前のロック削除なので、PR #694のリトライはロックを消さずに再試行していたとみられます。3回リトライしても毎回同じ古いロックに当たって失敗した、という読み方です。

経緯 — 長期間報告が続いている既知issue

このロックファイル問題は一度きりの不具合ではなく、インストール処理の改善が入った直後から2026年1月上旬まで、報告と回避策の確認コメントが続いています。

issue #709はクローズされておらず、ロックファイル削除は暫定策のままです。

コメント欄では、anthropics/claude-codeリポジトリ側の別issue(#6200)でも同じrm -rf ~/.local/state/claude/locksが有効だったと紹介されています。claude-code-action経由のインストールに限らず、claude本体のインストーラー(CLIから直接claude install/claude updateを実行する場合)でも同じ症状が起きることがあるようです。

対処: ロックファイルを削除して再実行する

ロックファイルを手動で消せば、次のインストールやアップデートは通常どおり進みます。macOSとLinuxでは同じパスです。

rm -rf ~/.local/state/claude/locks
claude install

Windowsでは対応するディレクトリが異なります。

Remove-Item -Recurse -Force "$env:USERPROFILE\.local\state\claude"
claude install

issue内のログにあるとおり、エラーメッセージ自体が--forceでの上書きを案内しています。ロックファイルの場所を調べずに済ませたい場合は、こちらを先に試す手もあります。

claude install --force

ただし--forceでも直らない場合の手順も案内されています。issue #709のコメントでは、Windowsでclaude install --forceでも直らないときにstate\claude配下のファイルを削除するよう案内されています。--forceで解決しない場合は、上記のロックファイル削除に進んでください。

claude updateで止まったときは、さらに事情が変わります。v2.1.287の--helpで見ると、--forceを持つのはclaude installだけです。

claude install --help
claude update --help

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
 
Usage: claude update|upgrade [options]
 
Check for updates and install if available
 
Options:
  -h, --help  Display help for command

claude update(別名claude upgrade)のオプションは-hだけで、--forceを付けられません。更新の失敗では、ロックの削除が先の手になります。

claude install --forceの説明も「すでにインストール済みでも強制的にインストールする」で、古いロックを消すとは書かれていません。issue #709のコメントも、--forceで直らない場合に備えてロック側の削除を案内しています。

OS別のロックファイルの場所

ロックファイルの置き場所はOSで共通の考え方(ユーザーのローカル状態ディレクトリ配下)ですが、パスの書き方が変わります。

公式のインストール失敗の切り分けページが場所を挙げているのは、macOSとLinuxです。ロックファイルは~/.local/state/claude/にあり、ダウンロードしたバイナリは~/.claude/downloads/、ステージング中のダウンロードは~/.cache/claude/に置かれます。Windowsの%USERPROFILE%\.local\state\claudeは、issue #709のコメントで案内された場所です。

XDG_STATE_HOMEを設定している環境では、~/.local/stateの代わりにその値が使われると公式ページにあります。その場合の削除先は、その配下のclaude/locksです。

rm -rf "${XDG_STATE_HOME:-$HOME/.local/state}/claude/locks"

このstateディレクトリは別物です。Claude Codeアンインストールの手順が扱う~/.local/bin(バイナリ本体)や~/.local/share(インストール済みバージョン等)とは場所が違います。macOS・Linuxで削除するのはstate/claude/locksサブディレクトリだけです。issue #709のコメントで案内されているWindowsの手順だけは、state\claudeディレクトリ全体を削除する点に差があります。バイナリ本体は.local\bin側なので巻き添えにはなりにくいものの、影響範囲はやや広くなります。

GitHub Actions(claude-code-action)で再発を防ぐ

CI上でこのエラーが繰り返し起きる場合、ワークフローが実行のたびに新規インストールを試みていること自体が原因になりやすくなります。claude-code-actionのpath_to_claude_code_executable入力を使うと、自動インストールをスキップし、指定したバイナリをそのまま使わせられます。

- uses: anthropics/claude-code-action@main
  with:
    path_to_claude_code_executable: /usr/local/bin/claude
    claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}

事前にセットアップジョブでインストール・キャッシュしたバイナリのパスを渡す構成にすれば、毎回のジョブでインストールを再試行する必要がなくなり、インストール起因のタイムアウトは起きなくなります。アクションの自動インストールを使わない分、claudeのバージョン更新は自分で管理する必要があります。組織全体でワークフローを配布している場合は、GitHub Actionsの組織導入手順にある共有ワークフロー化と組み合わせられます。バイナリの差し替えも1箇所で管理できるようになります。

path_to_claude_code_executableを使わず、アクション自体のインストール処理を経由しない選択肢もあります。issue #709のコメントで共有された手動インストールの流れを、専用ステップとしてワークフローに組み込む形です。

インストーラーの配布元はdownloads.claude.aiです。issue内のコメントでは別のストレージURLが使われていましたが、下の例はdownloads.claude.aiに替えています。/usr/local/binへの書き込みとlinux-x64のバイナリを前提にしているので、ubuntu-latestのようなx64のLinuxランナー向けの例です。

- name: Install Claude Code manually
  run: |
    version=$(curl -fsSL "https://downloads.claude.ai/claude-code-releases/stable")
    curl -fsSL "https://downloads.claude.ai/claude-code-releases/$version/linux-x64/claude" -o /usr/local/bin/claude
    chmod +x /usr/local/bin/claude
- uses: anthropics/claude-code-action@main
  with:
    path_to_claude_code_executable: /usr/local/bin/claude
    claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}

この方法はclaude-code-actionのインストールステップを完全に迂回するため、ロック機構そのものの影響を受けません。引き換えに、バージョン追従とダウンロード先URLの維持は自分のワークフロー側の責任になります。actions/cacheでダウンロード済みバイナリをキャッシュしておけば、毎回のダウンロード自体も省略できます。

よくあるつまずき

~/.localディレクトリごと削除してしまうのが最も実害の大きい誤りです。issue #709のコメント欄でも、Windowsで.local全体を消す回避策が広まりかけました。しかし別のユーザーから「pipx・仮想環境・tmux・direnvなど多数のツールが道連れで壊れる」と指摘が入りました。消してよいのは.local\state\claudeのサブディレクトリだけで、.local全体は対象に含めません。

「Installation complete」の表示を信用してしまうのも典型的な見落としです。前述のとおりロック競合で失敗していても、ワークフローのログ上は成功表示が出ます。CI導入時は、インストール直後にclaude --versionを実行して終了コードを確認するステップを挟むと、この種の「見かけ上の成功」を早い段階で検知できます。

ローカルのclaude installとCI上の失敗を同じ原因と決めつけるのも避けたい点です。CI環境ではタイムアウトからの自動リトライが主因ですが、ローカル環境での発生原因はissue内では特定されていません。claude-code-actionには、ロックとは別の不具合の修正もあります。Claude Code v2.1.227は、allowed_non_write_usersを設定した環境でBashが全て失敗する不具合の修正です。ロック削除で直らない場合は、アクションとClaude Codeのバージョンも確かめます。メモリ不足でインストーラーごと強制終了する「Installation was killed」エラーとは症状も対処も別物です。エラーメッセージの文言で切り分けてください。

よくある質問

claude updateでも同じエラーは起きますか

起きます。issue #709には、2.0.72から2.0.73へのアップグレードでもロックファイルの削除で解決したという報告があります。claude install限定の不具合ではなく、既存インストールの更新経路でも同じロック機構が使われています。

ジョブをまたいでロックが残ることはありますか

issueで報告されている競合は、同一ジョブ内での1回目のタイムアウトと2回目のリトライの間で起きています。GitHub Hostedランナーは実行ごとに新しい環境で始まるため、別ジョブにロックが持ち越されることは考えにくい構成です。ただし、自己ホスト型ランナーのようにファイルシステムを使い回す構成では、前回のジョブが残したロックが次回の実行に影響する可能性があります。

レート制限のエラーと見分けるには

CIジョブの失敗はレート制限が原因のこともあり、ログだけでは区別しづらい場合があります。issueのコメントでは、レート制限は即座にAPI側から拒否されtotal_cost_usd: 0が返る一方、ロックファイルのエラーは、1回目の試行が120秒でタイムアウトした後の2回目の試行で出ています。失敗までの時間が長ければロック競合、即座に失敗していればレート制限を疑う切り分けです。

Windowsの「because it is being used by another process」と同じですか

別の症状です。公式のトラブルシューティングガイドはFailed to download binary: The process cannot access the file ... because it is being used by another processという別のエラーを扱っています。これはPowerShellインストーラーが%USERPROFILE%\.claude\downloadsへの書き込みでファイルロックに当たるエラーです。対処もRemove-Item -Recurse -Force "$env:USERPROFILE\.claude\downloads"と異なります。今回扱っているanother process is currently installing ClaudeはCLI自身のロック機構によるメッセージです。削除対象のディレクトリも文言も別物なので、エラーメッセージの文言で切り分けてください。

ロックファイルを削除しても直らない場合は

claude doctorを実行してインストール状態を確認したうえで、それでも失敗する場合は前述の手動インストール手順に切り替えてください。

まとめ

主役はロックファイルの削除で、--forceは補助です。GitHub Actionsで繰り返すなら、path_to_claude_code_executableでバイナリを固定してインストール自体を走らせない構成にするのが再発防止になります。