2026/04/07Claude Code

初心者向け導入・運用

Claude Codeが動かない？エラー別の解決法まとめ

Claude Codeのインストールでエラーが出た、実行中に動かなくなった――そんな経験はないでしょうか。私はClaude Codeを2025年10月から業務で使い続けており、クライアントへの導入支援も含めて、これまで数十パターンのエラーに遭遇してきました。

この記事では、私自身が実際に経験したトラブルと、導入支援の現場で非エンジニアの方から報告を受けたエラーを中心に、インストール時・実行時・環境別の3カテゴリに分けて解決法をまとめます。

Claude Codeエラー3分類マップ：インストール系・実行時エラー系・環境依存系

Claude Codeインストール時のエラーと解決法

「Node.js version 18 or higher required」と表示される

最も多いエラーです。Claude CodeをNode.js（npm）経由でインストールする場合、Node.js 18以上が必須です。

ターミナルでnode -vを実行し、バージョンが18未満であれば更新が必要です。nvm（Node Version Manager）を使っている場合は以下のコマンドで解決します。

nvm install --lts
nvm use --lts

私のクライアント支援の現場では、Homebrewで入れた古いNode.jsとnvmが競合していたケースが最も多く見られました。which nodeでパスを確認し、想定外のNode.jsを参照していないかチェックすることをおすすめします。

なお、2025年10月にAnthropicが公開したネイティブインストーラーを使えば、Node.jsのインストール自体が不要になります。特にプログラミング経験がない方には、こちらが圧倒的に簡単です。

「EACCES permission denied」が出る

macOS/Linuxでnpm install -gを実行したときに発生する権限エラーです。npmのグローバルインストール先ディレクトリの所有権が合っていないことが原因です。

sudo chown -R $(whoami) ~/.npm

このコマンドで権限を修正できます。ただし、sudoでnpm installを実行するのはセキュリティ上おすすめしません。npmの公式ドキュメントでも、ホームディレクトリ内にグローバルインストール先を設定する方法が推奨されています。

ネイティブインストーラーで依存ライブラリ不足

Alpine LinuxなどmuslベースのLinuxディストリビューションでネイティブインストーラーを使う場合、libgcc・libstdc++・ripgrepが必要です。

apk add libgcc libstdc++ ripgrep

一般的なUbuntuやmacOSでは発生しません。サーバー環境やDocker内でClaude Codeを使うケースで注意が必要です。

WSLで「not supported on Windows」と出る

WSL（Windows Subsystem for Linux）内でインストールしているはずなのに、Windowsと判定されるケースです。原因はWSLがWindowsのnpmを参照していることにあります。

which npm
# /mnt/c/... と表示されたらWindows版を参照している

Linux側のNode.jsを使うように設定し直すか、--force --no-os-checkオプションを付けてインストールします。

npm install -g @anthropic-ai/claude-code --force --no-os-check

私の経験では、Windows環境の方には2025年リリースのネイティブWindows版を案内するのが最もスムーズです。WSLを経由する必要がなくなり、セットアップの手間が大幅に減ります。

APIキー・プランの認証エラー

インストール後にclaudeコマンドを実行しても、認証画面でエラーが出るケースです。考えられる原因は3つあります。

Anthropicアカウントの契約プランがClaude Codeに対応していない（Proプラン以上が必要）
APIキーを手動設定している場合、キーにスペースや改行が混入している
企業のプロキシ環境でAnthropicのAPIサーバーへの通信がブロックされている

まずAnthropicコンソールで契約状態を確認してください。Pro（$20/月）以上であればClaude Codeを使えます。

Claude Code実行時のエラーと解決法

料金プラン比較：Claude Code vs Gemini Code Assist

「Rate limit reached」（429エラー）

使っていると突然「Rate limit reached」と表示されて操作を受け付けなくなります。私自身、Max 5x（$100/月）プランの時代にLP改修とSEO記事14本を1セッションで並列処理した際、約3時間で制限に到達しました。

Claude Codeのレート制限は3つの独立したカウンターで管理されています。

RPM（Requests Per Minute）: 1分あたりのリクエスト回数
TPM（Tokens Per Minute）: 1分あたりのトークン消費量
日次クォータ: 1日の総消費量

ダッシュボードの使用率はクォータのみを反映しているため、表示が低くても分単位の制限に引っかかることがあります。

対処法:

/model sonnetで軽量モデルに切り替える（即座に使える）
数分待ってから再実行する（RPM/TPMはローリングウィンドウ）
大量のテキスト読み込み＋リライトの並列実行を避ける

この経験以降、私はClaude CodeでしかできないタスクのみをClaude Codeに集中させ、単純な調査やデータ整形は別のAIに委譲する運用に変えました。トークン消費を意識するだけで、制限到達の頻度が大幅に減ります。

コンテキスト超過（トークン上限エラー）

長時間のセッションや大量のファイルを読み込ませた場合に発生します。Claude Codeは1回のやり取りごとに、システムプロンプト＋会話履歴＋読み込んだファイル内容＋ツール実行結果をすべてトークンとして送信しています。

即座に解決する方法:

/compact — 会話履歴を圧縮して要点だけ残す
/clear — 会話をリセットしてゼロから始める

私の運用では、コンテキストが溜まる前に新しいセッションを始めることを心がけています。大量のコンテキストで精度を上げるアプローチより、必要最小限のコンテキストで的確に指示を出す方が、結果的にアウトプットの質が高くなります。

MCP接続エラー

MCP（Model Context Protocol）で外部サービスと連携する際、「Connection failed」「timed out after 30000ms」といったエラーが発生することがあります。

私がMicroCMSやSupabaseとのMCP連携で経験したよくある原因トップ3は以下です。

設定JSONでの相対パス指定: ~/server.jsではなく/Users/xxx/server.jsのように絶対パスを使う
ディレクトリパスに日本語やスペースを含む: Claude Codeのサンドボックスがパスを正しく解釈できない
サイレント接続失敗: エラーメッセージなしで接続に失敗し、MCP機能が無効のまま動作する

サイレント失敗は厄介で、MCPを使おうとして初めて気づくパターンです。VS Codeなら「Developer: Reload Window」で再接続を試みるのが確実です。CLIの場合はclaude mcp listで接続状態を確認してください。

パーミッション拒否（サンドボックスエラー）

Claude Codeはセキュリティのためにサンドボックス内で動作しています。特定のファイルやディレクトリへのアクセスが拒否される場合があります。

プロジェクトディレクトリ外のファイルにアクセスしようとしている
FacebookのWatchman（ファイル監視ツール）がサンドボックスと競合している

Watchmanの競合は特にReact Native開発者に多く見られます。Watchmanを無効化するか、サンドボックスの対象から除外することで解決します。

ネットワーク・SSLエラー

企業ネットワークやVPN経由で使用する場合、プロキシやSSL証明書の問題でAPIに接続できないことがあります。

# プロキシ設定
export HTTPS_PROXY=http://your-proxy:8080

# SSL証明書の問題がある場合
export NODE_TLS_REJECT_UNAUTHORIZED=0  # 一時的な回避策

注意: NODE_TLS_REJECT_UNAUTHORIZED=0はセキュリティリスクがあるため、一時的な動作確認のみに使用してください。本格的に使う場合は、プロキシのCA証明書をシステムに登録する必要があります。

環境別のトラブルシューティング

macOSでのトラブル

macOSはClaude Codeとの相性が最も良い環境です。それでも以下のトラブルが発生することがあります。

HomebrewのNodeとnvmの競合: brew uninstall nodeでHomebrew版を削除し、nvmに一本化する
npmグローバルの権限問題: 前述のchownコマンドで解決
Xcodeコマンドラインツール未インストール: xcode-select --installを実行

私はmacOS環境でClaude Codeを常用しています。ネイティブインストーラーを使えば、Node.jsの管理自体を気にする必要がなくなるため、macOSユーザーにはネイティブインストーラーを強くおすすめします。

Windowsでのトラブル

Windowsは2025年にネイティブ対応されましたが、まだ固有のトラブルが残っています。

Git for Windowsが未インストール: ネイティブインストーラー使用時も必要
PATHが通っていない: インストール後にclaudeコマンドが認識されない場合、PowerShellを管理者権限で再起動
VS Code拡張の「Not Responding」: Windows 11で多発。Claude DesktopとVS Code拡張を同時起動しないことが回避策
パスに日本語やスペース: ユーザー名が日本語の場合、別のインストール先を指定する

私が導入支援をしたクライアントの約半数がWindows環境でしたが、ネイティブWindows版の登場で、以前のWSL必須時代と比べてセットアップの難易度は大幅に下がったと感じています。