トラブルシューティング

Claude Codeの「Auto-update failed」の直し方【Mac/Windows実践チェックリスト】

「Auto-update failed」と表示されたまま起動しない、更新後に「permission denied」になる——このエラーは原因のパターンがある程度決まっています。この記事では、まず試すべき手順を上から順に実行するだけで直せるチェックリスト形式でまとめました。原因を詳しく知りたい場合は、実際の調査過程をまとめた関連記事も用意しています。

まず確認：症状のパターン

「Auto-update failed」関連のエラーは、表示される内容によって原因が絞り込めます。自分の症状に近いものを確認してください。

表示されるメッセージ	主な原因	対処のステップ
`Auto-update failed · Try claude doctor or npm i -g @anthropic-ai/claude-code`	更新処理そのものの失敗	ステップ1・2
`zsh: permission denied: claude`	更新後の実行ファイルが壊れている（Mac）	ステップ2・3
`error: claude native binary not installed`	本体バイナリが正しく設置されていない	ステップ2・3
`auto-update failed: claude.exe in use`	実行中プロセスによるファイルロック（Windows）	ステップ4
npmエラー `ENOTEMPTY`	前回更新の一時ディレクトリが残存	ステップ3

ステップ1：まず claude doctor を実行する

手順

claudeが起動できる状態なら、セッション内で/doctorを実行する
claudeコマンド自体が起動しない場合は、シェルから直接claude doctorを実行する
インストール・設定・拡張機能・コンテキスト使用量の自動チェックが行われ、可能な修正は確認の上で適用される

公式ドキュメントでも「claudeが全く起動しない場合はシェルからclaude doctorを実行する」ことが最初の対処として案内されています。多くのケースはこの時点で解決します。

# claudeコマンド自体が起動しない場合
claude doctor

ステップ2：手動で再インストールする

claude doctorで直らない場合は、npmパッケージを手動で入れ直します。

npm install -g @anthropic-ai/claude-code@latest

⚠ 実行中のClaude Codeは必ず全て閉じる

ターミナル・VS Code拡張・JetBrainsプラグインなど、Claude Codeを起動している窓口をすべて閉じてから再インストールしてください。特にVS Code拡張が有効なまま残っていると、実行ファイルがロックされて再インストールが失敗します（詳しくはステップ4）。

ステップ3：残存ファイルが原因の場合（ENOTEMPTY等）

ステップ2でも同じエラーが再発する場合、前回の更新処理が残した一時ファイル・退避ディレクトリが原因のことがあります。npmは更新のたびに既存のインストールを一時ディレクトリへ退避しようとしますが、前回の退避先がすでに存在していると衝突して失敗します。

Mac（Homebrew環境）の場合

# インストール場所を確認
ls -la /opt/homebrew/lib/node_modules/@anthropic-ai/

# 「.claude-code-」で始まる残存ディレクトリがあれば削除してから再インストール
rm -rf /opt/homebrew/lib/node_modules/@anthropic-ai/.claude-code-*
npm install -g @anthropic-ai/claude-code@latest

この現象を実際に調査した過程（壊れたバイナリが約500Bのプレースホルダーになっていた事例）はAuto-update failedの原因調査記事で詳しく解説しています。「なぜこうなるのか」を理解したい方はあわせてご覧ください。

Windows・その他の環境の場合

# グローバルインストール先を確認
npm root -g

# 表示されたパスの中の @anthropic-ai\claude-code 関連の
# 一時フォルダ（ランダムな文字列がついたもの）があれば手動削除してから再実行
npm install -g @anthropic-ai/claude-code@latest

ステップ4：Windowsで「claude.exe in use」と出る場合

Windowsでは、自動更新がclaude.exeを新しいバージョンに差し替える際、実行中の別プロセスがファイルをロックしているためにこのエラーが起きるケースが多く報告されています。よくある原因は次の3つです。

VS Code拡張が起動したまま：拡張機能がバイナリをロックし続け、更新の書き込みに失敗する
別のターミナルでClaude Codeが起動中：他のウィンドウ・タブでプロセスが生きている
デスクトップアプリのバックグラウンドサービス：関連プロセスが排他ロックを保持している

手順

VS Codeのウィンドウをすべて閉じる（拡張機能ごと終了させる）
タスクマネージャーでclaude・Claude関連のプロセスが残っていないか確認し、あれば終了する
それでも直らない場合はPCを再起動する（ファイルロックがOSレベルで残っているケースがあります）
再起動後、ターミナルを新しく開いてnpm install -g @anthropic-ai/claude-code@latestを実行する

ℹ 応急処置：.oldファイルを戻す

更新処理はclaude.exeをclaude.exe.old.（タイムスタンプ）のような名前にリネームしてから新バージョンに差し替えようとします。差し替えに失敗するとclaude.exe自体が消えた状態になることがあります。この場合、.oldファイルを元のclaude.exeという名前に戻せば、ひとまず動く状態に復旧できます（バージョンは更新前のものに戻ります）。恒久対処ではないため、復旧後は改めてステップ2の手動再インストールを行ってください。

それでも直らない場合

ターミナルを再起動してからclaude --versionを実行し、バージョン表示が更新されているか確認する（PATHのキャッシュが古いままのことがあります）
error: claude native binary not installedが出る場合は、実行ファイルの権限・実体が壊れている可能性が高く、起動しない原因と直し方の記事でより詳しい切り分け方法を解説しています
上記すべてで解決しない場合は、GitHubの公式リポジトリで同様の報告がないか検索するか、/feedbackでAnthropicに直接報告してください

再発を防ぐには

✓ 予防のポイント

Claude Codeの自動更新中は、他のターミナル・VS Code拡張でClaude Codeを同時に起動しない
更新エラーが出たら、放置せず早めにclaude doctorで状態を確認する習慣をつける
手動更新する場合はnpm install -g @anthropic-ai/claude-code@latestを定期的に使い、自動更新に頼りきらない運用も選択肢