ClaudeCodeを使い始めたばかりのころは、思いがけないエラーに悩まされることがあります。この記事では、初心者がよくハマる10パターンのエラーと解決策を分かりやすく解説します。
エラーメッセージを見ると難しそうに見えますが、原因が分かれば解決は簡単なものがほとんどです。ぜひ参考にしてください。
ClaudeCodeのインストール方法は ClaudeCodeのインストール方法 で解説しています。
エラー1: APIキーが認識されない
エラーメッセージ
Error: ANTHROPIC_API_KEY is not set
Authentication error: invalid x-api-key
原因
APIキーが設定されていない、または設定方法が間違っています。
解決策
手順1: APIキーを環境変数に設定する
Macの場合、ターミナルで以下を実行します:
echo 'export ANTHROPIC_API_KEY="sk-ant-あなたのAPIキー"' >> ~/.zshrc
source ~/.zshrc
手順2: 設定できているか確認する
echo $ANTHROPIC_API_KEY
sk-ant-で始まるキーが表示されれば成功です。
手順3: APIキーが有効か確認する
Anthropicのコンソール（console.anthropic.com）にログインして、APIキーが有効になっているか確認してください。
よくある間違い
- APIキーに余分なスペースが含まれている
- 引用符（
"）を入れ忘れている - bashを使っているのに
.zshrcを編集している（bashの場合は.bashrc）
エラー2: ClaudeCodeのインストールが失敗する
エラーメッセージ
npm ERR! code EACCES
npm ERR! syscall access
permission denied
原因
npmのグローバルインストールに必要な権限がありません。
解決策
方法1: sudoを使わずにnpmのインストール先を変更する（推奨）
# npmのグローバルディレクトリをホームに変更
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc
# あらためてインストール
npm install -g @anthropic-ai/claude-code
方法2: sudoを使う（簡単だが推奨はしない）
sudo npm install -g @anthropic-ai/claude-code
Node.jsのバージョンが古い場合
# Node.jsのバージョン確認
node --version
# v18以上が必要。古い場合はNode.jsを更新
# nvmを使っている場合
nvm install --lts
nvm use --lts
エラー3: `claude: command not found`
エラーメッセージ
zsh: command not found: claude
bash: claude: command not found
原因
ClaudeCodeはインストールされているが、実行ファイルの場所がPATHに含まれていません。
解決策
手順1: インストール先を確認する
npm list -g @anthropic-ai/claude-code
手順2: npmのグローバルパスを確認する
npm config get prefix
表示されたパスに /bin を追加したものをPATHに追加します。
手順3: PATHを設定する
# 例: /usr/local/lib/node_modules の場合
echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
手順4: ターミナルを再起動して確認
claude --version
エラー4: 権限エラーでファイルが操作できない
エラーメッセージ
EACCES: permission denied, open '/path/to/file'
Error: EPERM: operation not permitted
原因
ClaudeCodeが操作しようとしているファイルやフォルダへのアクセス権限がありません。
解決策
手順1: ファイルの権限を確認する
ls -la /対象のパス
手順2: 権限を変更する
# ファイルに書き込み権限を付与
chmod 644 ファイル名
# フォルダに実行・書き込み権限を付与
chmod 755 フォルダ名
手順3: 所有者を確認・変更する
# 現在の所有者確認
ls -la ファイル名
# 所有者を自分に変更
sudo chown $(whoami) ファイル名
Macのセキュリティ設定が原因の場合
Macの「システム環境設定 → プライバシーとセキュリティ → フルディスクアクセス」にターミナルを追加してください。
エラー5: レート制限エラー
エラーメッセージ
Error: 429 Too Many Requests
RateLimitError: You have exceeded your rate limit
原因
短時間に大量のリクエストを送り、APIの利用制限に達しました。
解決策
短期的な対処:
少し時間を置いてから再実行します。通常は数分〜1時間程度待てば解消します。
# しばらく待ってから再実行
sleep 60 && claude "続きをお願いします"
根本的な対処:
- Anthropicコンソールで使用量を確認し、プランのアップグレードを検討する
- 一度に送るリクエストの量を減らす
- 大きな作業を小さく分割して実行する
エラー6: コンテキスト長のエラー
エラーメッセージ
Error: context_length_exceeded
This model's maximum context length is exceeded
原因
一度に送ったテキスト（コードや会話の履歴）がAIが処理できる上限を超えました。
解決策
方法1: 会話をリセットする
# 新しいセッションを開始（/clearコマンド）
# ClaudeCode内で
/clear
方法2: ファイルを分割する
大きなファイルを一度に処理させるのではなく、関係する部分だけを指定します:
# 特定のファイルだけ読ませる
claude "src/components/Button.tsxのみを修正して"
方法3: CLAUDE.mdで不要な情報を減らす
CLAUDE.mdに書いている内容が多すぎる場合、必要最低限に絞ります。
エラー7: JSONパースエラー・出力が壊れる
エラーメッセージ
SyntaxError: Unexpected token in JSON
Failed to parse response
原因
ネットワークの不安定や、AIの出力が途中で途切れた可能性があります。
解決策
手順1: 同じコマンドを再実行する
多くの場合、再実行すれば解決します:
# 直前のコマンドを再実行
claude "もう一度お願いします"
手順2: ストリーミングをオフにして実行する
claude --no-stream "あなたの質問"
手順3: ClaudeCodeを最新版に更新する
npm update -g @anthropic-ai/claude-code
claude --version
エラー8: gitコマンドが失敗する
エラーメッセージ
fatal: not a git repository
error: failed to push some refs
原因
gitリポジトリが初期化されていない、またはリモートリポジトリの設定が間違っています。
解決策
gitリポジトリが初期化されていない場合:
# gitリポジトリを初期化
git init
# 初回コミット
git add .
git commit -m "initial commit"
リモートへのpushが失敗する場合:
# リモートの設定を確認
git remote -v
# リモートを追加（GitHubの場合）
git remote add origin https://github.com/ユーザー名/リポジトリ名.git
# pushの再試行
git push -u origin main
エラー9: Node.js / npmのバージョン問題
エラーメッセージ
Error: The engine "node" is incompatible with this module
Requires Node.js version >=18.0.0
原因
使用しているNode.jsのバージョンが古く、ClaudeCodeの動作要件を満たしていません。
解決策
現在のバージョン確認:
node --version
npm --version
Node.jsの更新（nvmを使う方法・推奨）:
# nvmのインストール（まだの場合）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.zshrc
# 最新のLTS版をインストール・使用
nvm install --lts
nvm use --lts
# バージョン確認
node --version # v20以上になっていればOK
Node.jsの更新（公式サイトから・シンプルな方法）:
Node.jsの公式サイト（nodejs.org）からLTS版をダウンロードしてインストールします。
エラー10: Windows環境での文字化け・動作不良
エラーメッセージ（症状）
- 日本語が文字化けして表示される
- コマンドが認識されない
- パスの区切り文字（
\と/）でエラーが起きる
原因
ClaudeCodeはLinux/Mac環境を主に想定して作られています。Windows環境では追加の設定が必要です。
解決策
WSL2（Windows Subsystem for Linux）の使用を強く推奨します:
# PowerShellで実行（管理者権限）
wsl --install
# Ubuntuが入ったら、その中でClaudeCodeをインストール
Windows Terminalの文字コード設定:
# PowerShellで文字コードをUTF-8に設定
[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
chcp 65001
環境変数の設定（Windowsの場合）:
コントロールパネル → システム → 環境変数 → 新規作成で ANTHROPIC_API_KEY を追加します。
エラーが解決しないときの対処法
上記で解決しない場合は、以下の方法を試してください。
ClaudeCodeの完全再インストール
# アンインストール
npm uninstall -g @anthropic-ai/claude-code
# キャッシュのクリア
npm cache clean --force
# 再インストール
npm install -g @anthropic-ai/claude-code
ログを確認する
# 詳細なログを出力して実行
claude --verbose "あなたの質問"
公式ドキュメント・GitHubを確認する
ClaudeCodeのGitHubリポジトリのIssuesで同じ問題が報告されていないか確認してみましょう。
まとめ
ClaudeCodeでよく起きるエラー10パターンを解説しました。
| # | エラー | 主な原因 | 解決のポイント |
|---|---|---|---|
| 1 | APIキーエラー | 環境変数未設定 | .zshrcにexport ANTHROPIC_API_KEYを追加 |
| 2 | インストール失敗 | 権限不足 | npmのインストール先を変更 |
| 3 | command not found | PATHが通っていない | PATHにnpmのbinを追加 |
| 4 | 権限エラー | ファイルアクセス権限なし | chmodまたはchownで権限変更 |
| 5 | レート制限 | リクエスト過多 | 少し待って再実行 |
| 6 | コンテキスト長超過 | テキストが長すぎ | /clearでリセットか分割実行 |
| 7 | JSONパースエラー | ネットワーク不安定 | 再実行またはストリーミングオフ |
| 8 | gitエラー | リポジトリ未初期化 | git initから実行 |
| 9 | Node.jsバージョン | バージョンが古い | nvmで最新版に更新 |
| 10 | Windows文字化け | OS非対応 | WSL2を使用 |
ほとんどのエラーは環境設定の問題で、手順通りに対処すれば解決できます。エラーが出てもあきらめず、メッセージをよく読んで対応してみてください。