CodeCraft Lab

よくあるエラーと対処法まとめ

インストール失敗、認証エラー、タイムアウト等の頻出エラーとその解決方法をQ&A形式で解説します

かんたん13分で読了
トラブルシューティングエラーFAQ

はじめに

Claude Codeを使っていると、インストール時のエラーから実行中のトラブルまで、さまざまな問題に遭遇することがあります。この記事では、よくあるエラー10個をQ&A形式で解説します。エラーメッセージから素早く原因を特定し、適切な対処ができるようになりましょう。

Q1. npm install でパーミッションエラーが出る

症状:

EACCES: permission denied

インストール中に EACCES というエラーが表示され、インストールが完了しない。

原因: インストール先ディレクトリ（~/.local/bin/ や ~/.claude/）への書き込み権限がない。

対処法:

現在はネイティブインストーラーの利用が推奨されています。npmでの問題が発生した場合は、ネイティブインストーラーに切り替えましょう。

# ネイティブインストーラーを使用（推奨）
curl -fsSL https://claude.ai/install.sh | bash

ディレクトリの書き込み権限を確認・修正するには以下を実行します。

# 権限を確認
test -w ~/.local/bin && echo "書き込み可能" || echo "書き込み不可"
 
# 権限を修正
sudo mkdir -p ~/.local/bin
sudo chown -R $(whoami) ~/.local
sudoでnpm installを実行しない

sudo npm install -g は権限の問題を回避できますが、グローバルパッケージがroot所有になり、後で別の問題を引き起こします。ネイティブインストーラーを使うのが最も安全です。

Q2. claude コマンドが見つからない

症状:

zsh: command not found: claude

インストールは成功したように見えるが、claude コマンドを実行できない。

原因: インストールディレクトリ（~/.local/bin/）がシェルのPATHに含まれていない。

対処法:

まず、PATHに含まれているか確認します。

echo $PATH | tr ':' '\n' | grep -Fx "$HOME/.local/bin"

出力がなければ、PATHに追加します。

# zshの場合（macOSのデフォルト）
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
 
# bashの場合（Linuxのデフォルト）
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

設定後、バージョンが表示されれば成功です。

claude --version

Q3. 認証エラー（トークン期限切れ）

症状:

Claude Codeがセッション開始時や操作中に再ログインを求めてくる。または 403 Forbidden エラーが表示される。

原因: OAuthトークンが期限切れになっている。または、古い ANTHROPIC_API_KEY 環境変数が設定されている。

対処法:

ログアウトして再認証する

Claude Code内で以下を実行します。

/logout

その後、Claude Codeを再起動して認証をやり直します。

claude

環境変数を確認する

古いAPIキーが設定されていないか確認します。

echo $ANTHROPIC_API_KEY

不要なキーが設定されていたら解除します。

unset ANTHROPIC_API_KEY

~/.zshrc や ~/.bashrc に export ANTHROPIC_API_KEY=... の行がないかも確認しましょう。

認証状態を確認する

Claude Code内で /status を実行すると、どの認証方法が使用されているかを確認できます。

Q4. ネットワーク接続エラー（プロキシ環境）

症状:

Failed to fetch version from downloads.claude.ai

または TLS connect error、Could not resolve host などのエラーが表示される。

原因: 企業のプロキシやファイアウォールがClaude CodeのAPI通信をブロックしている。

対処法:

まず、ダウンロードサーバーへの接続を確認します。

curl -sI https://downloads.claude.ai/claude-code-releases/latest

HTTP/2 200 が返ればサーバーには到達できています。到達できない場合は、プロキシ設定を行います。

export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080

企業のTLS検査プロキシを使っている場合は、CA証明書の設定も必要です。

export NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.pem
プロキシ情報の確認方法

プロキシのURLがわからない場合は、IT部門に問い合わせるか、ブラウザのプロキシ設定を確認してください。macOSなら「システム設定 > ネットワーク > プロキシ」から確認できます。

Q5. コンテキスト長の超過

症状:

会話が長くなると、レスポンスが不安定になったり、自動コンパクションが繰り返し発生する。または Autocompact is thrashing というエラーが表示される。

原因: 会話のコンテキストがモデルのウィンドウサイズを超えた。巨大なファイルの読み込みや、長時間の会話が原因になりやすい。

対処法:

# コンテキストを手動で圧縮する
/compact
 
# 特定の内容だけ残して圧縮する
/compact 計画とdiffだけ残して
 
# 完全にリセットする（会話履歴は消える）
/clear

予防策として、以下を心がけましょう。

  • 大きなファイルは全体ではなく特定の行範囲や関数を指定して読ませる
  • 1つの会話でテーマを大きく変えず、新しいタスクは新しいセッションで始める
  • 大規模なファイル操作はサブエージェントに委任する

Q6. ファイルの読み書き権限エラー

症状:

Claude Codeがファイルを読み取れない、または編集できないというエラーが表示される。

原因: 権限設定の deny ルールでファイルへのアクセスがブロックされている。または、OSレベルのファイル権限が不足している。

対処法:

権限設定を確認します。

/permissions

特定のファイルがdenyリストに含まれていないか確認してください。よくあるのは .env ファイルに対するdenyルールが広すぎるケースです。

{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)"
    ]
  }
}

OSレベルの権限問題の場合は、ファイルのパーミッションを確認します。

ls -la 対象ファイル
Read/Editのパスパターン

Read(./src/*) は src/ 直下のファイルのみにマッチします。サブディレクトリ全体を含めるには Read(./src/**) のように ** を使ってください。

Q7. git操作でのエラー

症状:

Claude Codeがgitコマンドの実行時に権限エラーを表示する。または、意図しないブランチでの操作が行われそうになる。

原因: gitコマンドがallowリストに含まれていない。または、CLAUDE.mdで制約が明記されていない。

対処法:

安全なgitコマンドをallowリストに追加します。

{
  "permissions": {
    "allow": [
      "Bash(git status *)",
      "Bash(git diff *)",
      "Bash(git log *)",
      "Bash(git add *)",
      "Bash(git commit *)",
      "Bash(git branch *)",
      "Bash(git checkout *)"
    ],
    "deny": [
      "Bash(git push --force *)",
      "Bash(git reset --hard *)"
    ]
  }
}

git push は ask にしておくと、確認付きで実行できます。

{
  "permissions": {
    "ask": [
      "Bash(git push *)"
    ]
  }
}

Q8. MCPサーバー接続失敗

症状:

MCPサーバーのツールが利用できない。起動時にMCPサーバーの接続エラーが表示される。

原因: MCPサーバーの設定ファイル（.mcp.json）の記述ミス、サーバープログラムの未インストール、またはネットワークの問題。

対処法:

設定ファイルを確認する

.mcp.json の構文やパスが正しいか確認します。JSONの構文エラーが多い原因の一つです。

# JSONの構文を検証
cat .mcp.json | python3 -m json.tool

サーバープログラムの存在を確認する

設定で指定しているコマンドが実行可能か確認します。

# 例: npxで起動するサーバーの場合
npx -y @modelcontextprotocol/server-github --help

claude doctorで診断する

Claude Code内で /doctor を実行すると、MCPサーバーの接続状態を含む自動診断を実行できます。

/doctor

Q9. レスポンスが遅い・タイムアウト

症状:

Claude Codeの応答が極端に遅い、またはタイムアウトして操作が完了しない。

原因: コンテキストの肥大化、大量のファイル処理、ネットワークの遅延、またはプラグインやMCPサーバーの問題。

対処法:

まず、コンテキストサイズを削減してみましょう。

/compact

プラグインやMCPサーバーが原因かどうかを切り分けるには、セーフモードで起動します。

claude --safe-mode

セーフモードで改善した場合は、プラグインやMCPサーバーが原因です。1つずつ有効にして問題のあるものを特定しましょう。

その他の対策:

  • 大きなビルドディレクトリ（node_modules、dist 等）を .gitignore に追加する
  • 主要なタスクの区切りでClaude Codeを再起動する
  • ネットワーク環境を確認する（VPN経由の場合は特に遅延が発生しやすい）
メモリ使用量が気になる場合

Claude Code内で /heapdump を実行すると、メモリ使用状況の分析ファイルがデスクトップに出力されます。問題をGitHubに報告する際に添付すると、原因特定に役立ちます。

Q10. claude doctor の使い方

症状:

問題が発生したが、原因がよくわからない。何から調べればよいかわからない。

原因: 複合的な問題や環境依存の問題は、一つ一つ確認するのが大変です。

対処法:

claude doctor は、インストール状態、設定、MCPサーバー、コンテキスト使用量などを自動的にチェックする診断ツールです。

Claude Codeのセッション内から実行する場合:

/doctor

Claude Codeが起動できない場合は、シェルから直接実行します:

claude doctor

/doctor が確認する主な項目:

  • インストールの整合性（バイナリの存在、バージョン）
  • 設定ファイルの構文エラー
  • MCPサーバーの接続状態
  • スキルの説明テキストの短縮状況
  • コンテキスト使用量
まず /doctor を試す

何か問題が起きたら、まず /doctor を実行するのがおすすめです。多くの問題は /doctor の出力から原因を特定できます。それでも解決しない場合は、/feedback コマンドでAnthropicに問題を報告しましょう。

まとめ

エラーの種類まず試すこと
インストール失敗ネイティブインストーラーを使う
コマンドが見つからないPATHを確認・追加する
認証エラー/logout して再認証する
ネットワークエラープロキシ設定を確認する
コンテキスト超過/compact で圧縮する
権限エラー/permissions で設定を確認する
git操作エラーallowリストにgitコマンドを追加する
MCP接続失敗/doctor で診断する
レスポンスが遅い--safe-mode で起動して原因を切り分ける
原因不明/doctor で自動診断する

問題が解決しない場合は、GitHub Issuesで既知の問題を確認するか、Claude Code内で /feedback コマンドを使ってAnthropicに報告してください。