Claude Code Auto-update failedで起動不能：ENOTEMPTYの直し方と再発防止策

Claude CodeのAuto-update failedとは？

Claude CodeのAuto-update failedは、Claude Codeが起動中に自動更新を試みたものの、更新処理が途中で失敗したときに表示されるエラーです。

今回の環境では、Claude Codeをしばらく起動していると以下のような表示が出ました。

Auto-update failed · Try claude doctor or npm i -g @anthropic-ai/claude-code

その時点ではClaude Codeのセッション自体は動いていました。しかし、exit で終了したあとに再度 claude を起動しようとすると、以前と同じように起動できない状態になりました。

claude
# zsh: permission denied: claude

この症状は、以前まとめた以下の記事とかなり近いものです。

違いは、今回はユーザーが手動で更新したのではなく、Claude Codeの自動更新が引き金になった点です。

実際に起きていたこと

まず、claude コマンドのリンク先を確認しました。

ls -la /opt/homebrew/bin/claude

結果は以下のような状態です。

/opt/homebrew/bin/claude
-> ../lib/node_modules/@anthropic-ai/claude-code/bin/claude.exe

Apple Silicon MacでHomebrew配下のNode.js/npmを使っている場合、npmのグローバルパッケージは /opt/homebrew 配下に入ります。そのため、claude は最終的に以下のファイルを実行します。

/opt/homebrew/lib/node_modules/@anthropic-ai/claude-code/bin/claude.exe

しかし、このファイルを確認すると、本来あるべきnative binaryではありませんでした。

ls -lh /opt/homebrew/lib/node_modules/@anthropic-ai/claude-code/bin/claude.exe

壊れていたときは、以下のように約500Bの小さなファイルになっていました。

-rw-r--r--  500B  claude.exe

正常な状態では、このファイルは100MB以上のMach-O arm64実行ファイルになります。今回の復旧後は以下のようになりました。

-rwxr-xr-x  206M  claude.exe
claude.exe: Mach-O 64-bit executable arm64

つまり、claude.exe が本体バイナリではなく、エラーを表示するだけのプレースホルダーに戻っていたことが原因です。

エラーの直接原因はENOTEMPTY

npmログを確認すると、自動更新の裏側で以下の処理が実行されていました。

npm install --global @anthropic-ai/claude-code

そして、更新処理は以下のエラーで失敗していました。

npm error code ENOTEMPTY
npm error syscall rename
npm error path /opt/homebrew/lib/node_modules/@anthropic-ai/claude-code
npm error dest /opt/homebrew/lib/node_modules/@anthropic-ai/.claude-code-2DTsDk1V
npm error ENOTEMPTY: directory not empty, rename ...

これは、npmが既存のClaude Codeディレクトリを一時退避しようとしたときに、退避先のディレクトリがすでに存在していて空ではなかった、という意味です。

今回残っていたのは以下のようなディレクトリです。

/opt/homebrew/lib/node_modules/@anthropic-ai/.claude-code-2DTsDk1V

これはClaude Codeの履歴や設定ではありません。npmがパッケージ更新時に使う退避用の一時ディレクトリです。

この一時ディレクトリが残ったままだと、次の更新時にも同じ場所へ退避しようとして衝突し、また更新に失敗します。今回、同じような破損が2回起きた理由はここにあります。

なぜpermission deniedになるのか

permission denied: claude という表示だけを見ると、ファイル権限の問題に見えます。

しかし今回の本質は、単なるchmod不足ではありません。

壊れていた claude.exe は、以下のような状態でした。

-rw-r--r--  500B  claude.exe

実行権限がないうえに、中身もnative binaryではなく、プレースホルダーのテキストファイルでした。

中身は以下のようなメッセージを出すためのものです。

Error: claude native binary not installed.
Either postinstall did not run
or the platform-native optional dependency was not downloaded

つまり、permission denied は表面的な症状です。根本原因は、自動更新に失敗してpostinstallが完了せず、native binaryが bin/claude.exe に配置されなかったことです。

修復手順

修復は、残っているnpmの退避用一時ディレクトリを削除し、Claude Codeを再インストールする流れです。

まず、一時ディレクトリを確認します。

ls -la /opt/homebrew/lib/node_modules/@anthropic-ai

以下のような .claude-code-* が残っていれば、今回と同じ原因の可能性が高いです。

.claude-code-2DTsDk1V

これを削除します。

rm -rf /opt/homebrew/lib/node_modules/@anthropic-ai/.claude-code-2DTsDk1V

次にClaude Codeを再インストールします。

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

特定バージョンで揃えたい場合は、バージョンを指定します。

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

最後に確認します。

claude --version

今回の復旧後は、以下のように表示されました。

2.1.126 (Claude Code)

なお、claude --version は対話セッションの起動確認ではなく、バイナリが実行できるかを見るための軽い疎通確認です。実際に使えるか確認するには、通常通り claude を起動します。

claude

再発防止策：自動更新を止める

今回のように自動更新が2回続けて破損の引き金になった場合、まず現実的なのはClaude Codeの自動更新を止めることです。

Anthropicの公式ドキュメントでは、DISABLE_AUTOUPDATER=1 で自動更新を無効化できると案内されています。

グローバル設定ファイルに以下を追加します。

{
  "theme": "light",
  "env": {
    "DISABLE_AUTOUPDATER": "1"
  }
}

設定ファイルの場所は以下です。

~/.claude/settings.json

この設定を入れると、Claude Code起動中にバックグラウンドで自動更新が走ることを防げます。

今後は、更新したいタイミングでClaude Codeを終了してから手動更新する運用にします。

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

この方法なら、少なくとも作業中に自動更新が走って claude.exe がプレースホルダーに戻るリスクは下げられます。

より根本的な対策：インストール方式を変える

今回の再発は、npmグローバルインストール方式とClaude Codeの自動更新の相性が悪いことが原因でした。

公式ドキュメントでも、auto-updaterのpermission系トラブルに対して、npm global方式からローカルインストールへ移行する方法が案内されています。

候補は以下です。

claude migrate-installer

または、native installerを使う方法もあります。

curl -fsSL https://claude.ai/install.sh | bash

ただし、インストール方式を変える場合は、既存のPATHや古いシンボリックリンクが残っていると混乱しやすくなります。

現在のインストール場所は、以下で確認できます。

which claude
readlink /opt/homebrew/bin/claude
claude doctor

公式ドキュメントでは、ローカルインストールでは ~/.claude/local/claude へのaliasが使われるケースがあると説明されています。

まずは自動更新を止めて様子を見る。まだ再発するようなら、npm global方式からローカル/native installer方式へ移行する。これが安全な順番です。

履歴や設定は消えるのか

今回の修復では、Claude Codeの会話履歴やプロジェクト設定には触れていません。

修復対象になったのは、以下のnpmパッケージ領域です。

/opt/homebrew/lib/node_modules/@anthropic-ai/claude-code/
/opt/homebrew/lib/node_modules/@anthropic-ai/.claude-code-*
/opt/homebrew/bin/claude

一方、Claude Codeの履歴や設定は以下のような場所にあります。

~/.claude/
~/.claude/settings.json
.claude/settings.local.json

今回変更したのは、再発防止のために ~/.claude/settings.json に DISABLE_AUTOUPDATER=1 を追加したことだけです。

プロジェクト内の .claude/settings.local.json や、会話履歴ファイルは削除していません。

よくある質問

`claude doctor` だけで直る？

claude doctor は状態確認には役立ちますが、今回のように bin/claude.exe 自体がプレースホルダーになっている場合、根本修復には再インストールが必要です。

`chmod +x claude.exe` で直る？

おすすめしません。

今回の claude.exe は実行権限がないだけでなく、中身がnative binaryではありませんでした。chmod +x で実行可能にしても、根本的には壊れたままです。

なぜ2回も起きた？

npmの退避用一時ディレクトリ .claude-code-* が残っており、自動更新のたびに同じようなrename衝突が起きたためです。

自動更新を止めない限り、Claude Code起動中にまた npm install --global @anthropic-ai/claude-code が走り、同じ問題を再発させる可能性があります。

公式にはどう対処するのがよい？

公式ドキュメントでは、自動更新を止める方法として DISABLE_AUTOUPDATER=1 が案内されています。また、npm global方式のpermission問題を避ける方法として、ローカルインストールやnative installerへの移行も案内されています。

まとめ

Claude Codeの Auto-update failed のあとに permission denied: claude で起動できなくなる場合、原因はClaude Codeの自動更新失敗である可能性があります。

今回のポイントは以下です。

Claude Code起動中に自動更新が走った
裏側では npm install --global @anthropic-ai/claude-code が実行されていた
npmが既存パッケージを退避しようとして ENOTEMPTY で失敗した
bin/claude.exe が500Bのプレースホルダーに戻った
結果として permission denied: claude になった
修復は .claude-code-* の削除と再インストール
再発防止には DISABLE_AUTOUPDATER=1 が有効
さらに根本的にはnpm global方式からローカル/native installer方式への移行が候補

今回のように2回以上再発している場合は、単に再インストールするだけでは不十分です。自動更新を止めるか、インストール方式を変えるところまで対応したほうが安定します。

参照元

Claude Code settings – Anthropic: https://docs.anthropic.com/en/docs/claude-code/settings
Set up Claude Code – Anthropic: https://docs.anthropic.com/en/docs/claude-code/getting-started
Troubleshooting – Anthropic: https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/troubleshooting
Advanced setup – Claude Code Docs: https://code.claude.com/docs/en/setup