👌

Claude Codeが突然使えなくなった時の解決法

に公開
Claude Code
tech

問題の症状

昨日まで正常に動作していた claude コマンドが、突然以下のエラーで動かなくなった

$ claude
zsh: command not found: claude

前提

  • OS: M4 MacbookPro
  • Node.jsバージョン管理: fnm
  • Node.jsバージョン: v22.18.0
  • パッケージマネージャー: npm 11.5.2
  • 問題のパッケージ: @anthropic-ai/claude-code

🔍 原因の調査

1. インストール状況の確認

まず、Claude Codeがインストールされているか確認

$ npm -g list
/Users/x/.local/share/fnm/node-versions/v22.18.0/installation/lib
├── @anthropic-ai/claude-code@0.5.2
├── corepack@0.33.0
└── npm@11.5.2

パッケージ自体はインストールされていることが確認

2. 実行ファイルの確認

次に、実際の実行ファイルがどこにあるか確認

$ ls -la /Users/x/.local/share/fnm/node-versions/v22.18.0/installation/bin/

出力結果：

lrwxr-xr-x@ 1 x staff  52  9 10 23:00 .claude-X7tXWpYu -> ../lib/node_modules/@anthropic-ai/claude-code/cli.js

💡 原因の特定

問題は、Claude Codeの実行ファイルが .claude-X7tXWpYu という隠しファイル名（ドットで始まる一時的な名前）になっていたこと

通常は claude という名前のシンボリックリンクが作成されるはずが、何らかの理由で正しくリンクが作成されていない

期待される状態

lrwxr-xr-x@ 1 x staff  52  9 10 23:00 claude -> ../lib/node_modules/@anthropic-ai/claude-code/cli.js

npmがグローバルパッケージをインストールする際、以下のプロセスで実行ファイルのシンボリックリンクを作成する：

  1. 一時的な名前（例: .claude-X7tXWpYu）でシンボリックリンクを作成
  2. 作成に成功したら、正式な名前（claude）にリネーム
  3. PATHから実行可能になる

今回の問題は、ステップ2のリネーム処理が何らかの理由で失敗したことが原因。

考えられる原因

  • npmのインストール/アップデート中の不具合
  • 権限の問題
  • fnmのNode.jsバージョン切り替え時の問題

✅ 解決方法

クリーンな再インストール

最も確実な解決方法は、完全に削除してから再インストールすること

# 1. 既存のClaude Codeを手動で削除
rm -rf /Users/x/.local/share/fnm/node-versions/v22.18.0/installation/lib/node_modules/@anthropic-ai/claude-code
rm -f /Users/x/.local/share/fnm/node-versions/v22.18.0/installation/bin/.claude-*
npm cache clean --force

# 2. クリーンな状態で再インストール
npm install -g @anthropic-ai/claude-code

# 3. 動作確認
claude --version

🎯 なぜこれで解決したのか

  1. 不完全なシンボリックリンクの削除

    • .claude-X7tXWpYu のような一時的な名前のリンクを削除

  2. パッケージの完全削除

    • node_modules 内のClaude Code本体も削除して、残骸を完全にクリーンアップ

  3. 正常な再インストール

    • npmが正しいシンボリックリンク（claude）を作成
    • 実行パスが正しく設定される

🔧 予防策

今後同じ問題を避けるために：

  1. 定期的なnpmキャッシュのクリア

    npm cache clean --force

  2. fnm使用時の注意点

    • Node.jsのバージョンを切り替えた後は、グローバルパッケージの確認を行う
    • 必要に応じて再インストール

  3. アンインストール時のエラーに注意

    • ENOTEMPTY エラーが出た場合は、手動削除してから再インストール

📝 まとめ

fnm環境でnpmのグローバルパッケージのシンボリックリンクが壊れた場合、通常の npm uninstall では解決できない。その場合は、手動で関連ファイルを削除してからクリーンインストールすることで解決できる。

この方法は、Claude Codeに限らず、他のnpmグローバルパッケージでも同様の問題が発生した場合に応用可

Discussion