Claude Code エラー対処法50種｜症状から逆引きで即解決【2026年版】

Claude Code のエラー対処法を症状から逆引きで即解決できる、トラブルシューティングの完全リファレンスです。「command not found で起動できない」「Please run /login から抜け出せない」「Your organization has disabled Claude subscription access で組織側に阻まれる」「急に遅い・雑になった」——エラー文字列を覚えていなくても、まず「症状」から該当セクションに飛べるように設計しました。ターミナル上で動作する特性上、Claude Code は OS・ネットワーク・認証・モデル・組織設定の5レイヤーすべてで環境依存のトラブルが起きやすいためです。

使い方は2通りです。エラー文字列が分かるならそのままコピペして逆引きインデックスから探す、分からないならすぐ下の「症状逆引き表」から探す。どちらも1分以内に「原因→直す手順」へ最短到達できます。50以上のエラーパターンを公式のエラーリファレンス・インストールトラブルシューティング・ランタイムトラブルシューティングから完全網羅し、日本人ユーザーがつまずきやすいWSL・組織管理・Pro/Maxプランの文脈を補強しています。

症状で即解決 — 症状逆引き表

エラー文字列を覚えていなくても大丈夫です。「いま起きている症状」に最も近い行を選び、解決セクションに直接ジャンプしてください。具体的なエラー文字列が分かる場合は、次のエラーメッセージ逆引きインデックスの方が速く到達できます。

こんな症状のとき	代表的なエラー例	解決セクション
そもそも起動しない・コマンドが見つからない	command not found: claude	command not found
インストールが完了しない・途中で止まる	EACCES / Killed / Exec format error	インストール・セットアップ系エラー
ログインできない・/login ループから抜けられない	Not logged in · Please run /login	Not logged in
組織・会社のアカウントで使えない	Your organization has disabled Claude subscription access	org disabled subscription
急に「雑になった」・回答品質が落ちた	（明確なエラーは出ない）	thinking budget
動作が重い・CPU/メモリ使用量が高い	Worker started ログが連続出力	高CPU/メモリ
使用量の上限で止まった	You've hit your session limit / 429	セッション・週間制限
会話が長くなりエラーで止まる	Prompt is too long / Autocompact is thrashing	Prompt too long
MCP サーバーに接続できない	Could not connect to MCP server	MCP 接続不可
API・ネットワークに繋がらない・プロキシ環境	ECONNREFUSED / SSL certificate verification failed	API 接続不可
IDE（VS Code / JetBrains）が反応しない	No available IDEs detected	IDE 統合のトラブル

どの症状にも当てはまらない、または原因の切り分けから始めたい場合は、まず /doctor で一括自己診断を実行してください。

エラーメッセージで即解決 — 逆引きインデックス（50+項目）

ターミナルや IDE に表示されたエラー文字列から、該当する解決セクションに直接移動できます。一致するエントリが見つからない場合は、上の症状逆引き表か、次のセクションで紹介する /doctor コマンドから切り分けてください。

カテゴリ	エラーメッセージ	該当セクション
インストール	command not found: claude / 'claude' is not recognized	command not found
インストール	zsh: permission denied: claude	permission denied
インストール	EACCES: permission denied	EACCES
インストール	Node.js version 18 or higher required	Node version
インストール	curl: (35) TLS connect error / unable to get local issuer certificate	TLS/SSL
インストール	bash: line 1: syntax error near unexpected token '<'（HTMLが返る）	install.sh が HTML
インストール	インストール中に Killed	低メモリ Killed
インストール	curl: (56) Failure writing output to destination	curl 56
インストール	Illegal instruction	Illegal instruction
インストール	Error loading shared library libstdc++.so.6	glibc/musl mismatch
インストール	dyld: Symbol not found _ubrk_clone / Abort trap: 6	dyld macOS
インストール	cannot execute binary file: Exec format error（WSL1）	WSL1 Exec format
インストール	'irm' is not recognized / The token '&&' is not valid	Windows install command
インストール	Claude Code on Windows requires either Git for Windows or PowerShell	Git for Windows
インストール	Claude Code does not support 32-bit Windows	32-bit PowerShell
インストール	The process cannot access the file (Windows install)	Windows lock
インストール	Docker でインストールがハング	Docker hang
インストール	Claude.exe が Claude Desktop を起動してしまう	Claude Desktop競合
インストール	App unavailable in region	対応国外
認証	Not logged in · Please run /login	Not logged in
認証	Invalid API key · Fix external API key	Invalid API key
認証	API Error: 403 · request not allowed	403 Forbidden
認証	This organization has been disabled	organization disabled
認証	Your organization has disabled Claude subscription access for Claude Code	org disabled subscription
認証	Routines are disabled by your organization's policy	Routines disabled
認証	OAuth token revoked / expired · Please run /login	OAuth トークン
認証	does not meet scope requirement user:profile	OAuth scope
認証	OAuth error: Invalid code	OAuth Invalid code
認証	OAuth ログインが WSL2/SSH/コンテナで失敗	WSL OAuth
認証	model not found / you may not have access to it	model not found
認証	Claude Opus is not available with the Claude Pro plan	Opus not available
認証	Could not load credentials / ChainedTokenCredential	Bedrock/Vertex/Foundry
レート制限	You've hit your session limit / weekly limit / Opus limit	セッション・週間制限
レート制限	Server is temporarily limiting requests (not your usage limit)	Server limit
レート制限	API Error: 429 Rate limit reached / Request rejected (429)	API 429
レート制限	API Error: 529 Overloaded	529 Overloaded
レート制限	Credit balance is too low	credit balance
コンテキスト	Prompt is too long	Prompt too long
コンテキスト	Autocompact is thrashing: the context refilled to the limit...	Autocompact thrashing
コンテキスト	Error during compaction: Conversation too long	Compaction too long
コンテキスト	Request too large (max 30 MB)	Request too large
コンテキスト	Image was too large	Image too large
コンテキスト	PDF too large / PDF is password protected	PDF errors
コンテキスト	Auto mode classifier transcript exceeded context window	Auto mode classifier
コンテキスト	Extra inputs are not permitted	gateway header strip
MCP	Could not connect to MCP server / Connection closed	MCP 接続不可
MCP	MCP ツールが Claude Code 内で表示されない	MCP 認識されない
モデル	There's an issue with the selected model	model issue
モデル	thinking.type.enabled is not supported for this model	thinking enabled
モデル	max_tokens must be greater than thinking.budget_tokens	thinking budget exceeds
モデル	API Error: 400 due to tool use concurrency issues	Tool use mismatch
パフォーマンス	CPU/メモリ使用量が異常に高い	高CPU/メモリ
パフォーマンス	応答が遅い / Worker started ログが連続出力	Worker クラッシュ
パフォーマンス	検索ツールがファイルを見つけられない	ripgrep
パフォーマンス	WSL で検索結果が不完全・遅い	WSL 検索
パフォーマンス	<model> is temporarily unavailable, so auto mode cannot determine...	Auto mode safety
パフォーマンス	「Claudeが雑になった」回答品質が低い	thinking budget
IDE	VS Code 拡張機能が応答しない	VS Code
IDE	No available IDEs detected（JetBrains）	JetBrains
ネットワーク	Unable to connect to API / ECONNREFUSED / ETIMEDOUT / fetch failed	API 接続不可
ネットワーク	SSL certificate verification failed / 企業プロキシ	SSL（実行時）
ネットワーク	x-deny-reason: host_not_allowed（cloud session）	host_not_allowed
ネットワーク	Usage Policy refusal	Usage Policy

OS別トラブル早見表

「同じ症状でもOSによって原因と対処が違う」を一目で確認できる早見表です。詳細は各セクションに進んでください。

症状	macOS	Linux	WSL2	Windows ネイティブ
command not found	~/.zshrc に export PATH="$HOME/.local/bin:$PATH"	~/.bashrc に同上	~/.bashrc に同上＋PATH競合に注意	User PATH に %USERPROFILE%\.local\bin を追加
permission denied	chmod +x ~/.local/bin/claude	chmod +x ~/.local/bin/claude	NTFS属性に注意・chmod +x	管理者権限不要・PATH優先順位を確認
バイナリ実行不能	dyld: Symbol not found _ubrk_clone → macOS 13+へ更新	Error loading shared library → glibc/musl確認	cannot execute binary file: Exec format error → WSL2へ変換	Claude Code does not support 32-bit Windows → 64-bit PowerShellを使う
TLS/SSL エラー	Keychain更新・NODE_EXTRA_CA_CERTS	ca-certificates 更新・NODE_EXTRA_CA_CERTS	Linux と同じ	CRYPT_E_NO_REVOCATION_CHECK には --ssl-revoke-best-effort
OAuth ログイン失敗	Keychainロック → security unlock-keychain	n/a（systemd-resolved競合に注意）	BROWSER環境変数を設定＋手動paste	Claude Desktop競合に注意
検索が遅い	n/a	n/a	クロスFS遅延 → /home/ 配置	n/a
シェル不在	n/a	n/a	n/a	Git for Windows か PowerShell が必須
インストールハング	n/a	OOM Killed → swap追加	Linux と同じ	The process cannot access the file → downloads削除

読み方: 「n/a（非該当）」となっている欄は、そのOSで該当エラーが原則発生しないことを意味します。一方、Linux で command not found が出る場合は ~/.bashrc に PATH を追加してください、と読みます。

まずやるべきこと — /doctor で一括自己診断

/doctor は、Claude Code に内蔵された自己診断コマンドです。エラーの原因を手動で一つずつ確認する前に、まず /doctor を実行することで問題を素早く切り分けられます。

実行方法

Claude Code が起動できる場合は、セッション内で以下を実行します。

/doctor

Claude Code がまったく起動しない場合は、シェルから直接実行します。

claude doctor

/doctor 出力結果の項目別読み解き表

/doctor は5つのカテゴリを診断します。それぞれの出力例と意味、典型的な対処を以下にまとめます。

診断項目	出力例（正常）	出力例（異常）	異常時の対処
インストール状態	Installation: OK (v1.x.x)	Installation: PATH issue / binary not found	シェル設定で ~/.local/bin を PATH に追加、または再インストール
設定の有効性	Configuration: OK	Configuration: JSON parse error in settings.json	~/.claude/settings.json の構文エラーを修正
MCP サーバー	MCP: 3/3 servers connected	MCP: 1/3 connected (2 failed)	.mcp.json のコマンドパス・環境変数・サーバー名制約を確認
コンテキスト使用量	Context: 23% used	Context: 91% used · auto-compact may trigger	/compact で圧縮、または /clear で新セッション
認証状態	Auth: Subscription (Pro)	Auth: token expired / Auth: API key invalid	/login で再認証、または unset ANTHROPIC_API_KEY

/doctor の出力で具体的な問題が特定されたら、以下の各セクションで詳しい解決手順を確認してください。/doctor 以外の便利なコマンドは Claude Codeのスラッシュコマンド一覧 で紹介しています。

Claude Codeエラーの3分類と切り分けフロー

Claude Codeで発生するエラーは、大きく3つのカテゴリに分類できます。エラーに遭遇したら、まずどのカテゴリに該当するかを判断し、該当セクションに直接ジャンプしてください。

カテゴリ	典型的な症状	該当セクション
インストール・セットアップ系	command not found、EACCES、TLS エラー、Exec format error、Illegal instruction、dyld、glibc/musl 不整合、Docker hang	インストール・セットアップ系エラー
実行時系	429、529、Prompt is too long、MCP 接続失敗、認証エラー、組織管理エラー、モデル選定エラー、Autocompact thrashing	認証・APIキー・組織管理エラー / レート制限・使用量系エラー / コンテキスト・メモリ系エラー / MCP接続エラーの体系的デバッグ / モデル選定・thinking budget エラー
環境依存系	IDE 応答なし、WSL 検索が遅い、プロキシ接続不可、x-deny-reason: host_not_allowed、VPN残骸、DNS不整合	IDE 統合のトラブル / ネットワーク・環境別トラブル

最短ルート: どのカテゴリかわからない場合は、/doctor を実行してください。インストール、設定、MCP、コンテキスト使用量、認証を一括で診断できます。

インストール・セットアップ系エラー

Claude Codeの導入・インストール手順で最も多いトラブルは、PATH の設定問題と権限エラーです。さらに2026年の最新ビルドでは、CPUのAVX命令セット要件・macOS 13以上の要件・glibc/musl 自動判定・WSL1の互換性などが新たに問題を引き起こすようになっています。

command not found: claude

エラーメッセージ:

OS	表示されるメッセージ
macOS	zsh: command not found: claude
Linux	bash: claude: command not found
Windows CMD	'claude' is not recognized as an internal or external command
PowerShell	claude : The term 'claude' is not recognized as the name of a cmdlet

原因: インストールは完了しているが、Claude Code のバイナリが配置されるディレクトリ（~/.local/bin）がシェルの PATH に含まれていません。

解決手順:

macOS（Zsh）の場合:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
claude --version

Linux（Bash）の場合:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
claude --version

Windows PowerShell の場合:

$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')
# ターミナルを再起動後に確認
claude --version

予防策: ネイティブインストーラー（curl -fsSL https://claude.ai/install.sh | bash）は PATH の設定を自動で行います。npm でグローバルインストールした場合にこの問題が起きやすいため、ネイティブインストーラーの利用を推奨します。

zsh: permission denied: claude

エラーメッセージ: zsh: permission denied: claude

原因: PATH には含まれているが、claude バイナリに実行権限（x ビット）が付与されていません。手動でファイルを移動した場合や、Windows ファイルシステムから WSL にコピーした場合、unzip で属性を保持しなかった場合に発生します。

解決手順:

# 1. バイナリの実体パスを確認
which claude

# 2. 実行権限を付与
chmod +x ~/.local/bin/claude

# 3. 確認
ls -la ~/.local/bin/claude
claude --version

ls の出力で -rwxr-xr-x のように x ビットが立っていれば正常です。

予防策: バイナリの再配置はネイティブインストーラーで行うか、cp -p で属性を維持してコピーしてください。CI/CD パイプラインでバイナリを配布する場合は tar を --preserve-permissions 付きで使うか、配布直後に chmod +x を必ず実行する手順を組み込みます。

EACCES: permission denied

エラーメッセージ: EACCES: permission denied

原因: ~/.local/bin/ や ~/.claude/ ディレクトリへの書き込み権限がありません。過去に sudo npm install -g を実行して root 所有になっているケースが大半です。

解決手順:

# ディレクトリの書き込み権限を確認
test -w ~/.local/bin && echo "writable" || echo "not writable"
test -w ~/.claude && echo "writable" || echo "not writable"

# 権限がない場合は修正
sudo mkdir -p ~/.local/bin
sudo chown -R $(whoami) ~/.local ~/.claude

予防策: sudo npm install -g でのインストールは避けてください。ネイティブインストーラーを使えばこの問題は発生しません。

Node.js version 18 or higher required

エラーメッセージ: Node.js version 18 or higher required

原因: Claude Code は Node.js 18 以上を必要としますが、システムにそれより古いバージョンがインストールされています。

解決手順:

# 現在のバージョンを確認
node --version

# nvm を利用している場合
nvm install 22
nvm use 22
nvm alias default 22

# Homebrew の場合（macOS）
brew install node@22
brew link --overwrite node@22

予防策: プロジェクトごとに .nvmrc を配置し、nvm use で自動切り替えを行えば、複数の Node バージョンが混在する環境でも事故を防げます。

TLS/SSL エラー

エラーメッセージ: curl: (35) TLS connect error や unable to get local issuer certificate

原因: 企業のプロキシやファイアウォールが TLS 通信をインターセプトしているケースが大半です。Windows では CRYPT_E_NO_REVOCATION_CHECK (0x80092012) や CRYPT_E_REVOCATION_OFFLINE (0x80092013) のように、証明書失効リスト（CRL）の取得が失敗する形でも発生します。

解決手順:

# 1. CA 証明書を更新（Ubuntu/Debian）
sudo apt-get update && sudo apt-get install ca-certificates

# 2. 企業プロキシ環境の場合、CA 証明書を指定してインストール
curl --cacert /path/to/corporate-ca.pem -fsSL https://claude.ai/install.sh | bash

# 3. インストール後、Claude Code の API 通信にも同じ証明書を適用
export NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.pem

Windows で CRL チェックが失敗する場合は次のコマンドを使います。

curl --ssl-revoke-best-effort -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

または WinGet を利用すると curl 経由を回避できます。

winget install Anthropic.ClaudeCode

予防策: 企業環境では、IT 部門から CA 証明書ファイルを入手し、NODE_EXTRA_CA_CERTS 環境変数をシェルプロファイルに永続的に設定しておきましょう。企業環境でのClaude Code導入 も参考にしてください。

インストールスクリプトが HTML を返す

エラーメッセージ:

bash: line 1: syntax error near unexpected token `<'
bash: line 1: `<!DOCTYPE html>'

PowerShell では Invoke-Expression: Missing argument in parameter list. という形で現れます。

原因: インストール URL がスクリプトではなく HTML ページを返しています。地域制限、ネットワーク中断、または claude.ai/install.sh への一時的なルーティング異常が考えられます。GSC でも claude.ai install.sh 403 error のような検索が観測されており、この症状で迷う人は多いです。

解決手順:

# macOS の場合は Homebrew で代替インストール
brew install --cask claude-code

# Windows の場合は WinGet で代替インストール
winget install Anthropic.ClaudeCode

# または数分後に再試行
curl -fsSL https://claude.ai/install.sh | bash

予防策: HTML に「App unavailable in region」と表示される場合、お住まいの国では Claude Code が利用できません。Anthropic の対応国リストを確認してください。

低メモリ Linux サーバーで Killed

エラーメッセージ: インストール中に Killed が表示される

原因: Linux OOM Killer がメモリ不足のためプロセスを終了しました。Claude Code には少なくとも 4GB の RAM が推奨されます。

解決手順:

# スワップスペースを追加（2GB）
sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

# 再度インストール
curl -fsSL https://claude.ai/install.sh | bash

予防策: VPS やクラウドインスタンスでは、4GB 以上の RAM を持つインスタンスを使用するか、事前にスワップスペースを設定してください。

curl: (56) Failure writing output to destination

エラーメッセージ: curl: (56) Failure writing output to destination

原因: curl ... | bash の途中で接続が切れ、スクリプトが完全にダウンロードされませんでした。回線品質・ウイルス対策ソフトのスキャン・ディスクのI/O上限などが背景にあります。

解決手順:

# ダウンロードサーバーへの到達性を確認
curl -sI https://downloads.claude.ai/claude-code-releases/latest

# HTTP/2 200 が返れば一時的な障害なので再試行
curl -fsSL https://claude.ai/install.sh | bash

# 失敗が続くなら代替方法へ
brew install --cask claude-code   # macOS
winget install Anthropic.ClaudeCode   # Windows

予防策: 共有Wi-Fi など不安定な回線では、有線または安定したセルラー接続に切り替えてから再試行してください。企業環境では IT 部門に downloads.claude.ai のホワイトリスト登録を依頼します。

Illegal instruction（AVX欠如）

エラーメッセージ: Illegal instruction

原因: Claude Code のネイティブバイナリは AVX 命令セットを利用します。これに対応していない古いCPU（おおむね2013年以前の Intel・AMD）や、AVX をパススルーしていない仮想マシン（VPS / VM）では起動できません。アーキテクチャ自体が一致していない場合（ARMサーバーにx86バイナリを誤配布など）も同じメッセージで現れます。

解決手順:

# Linux: CPUがAVXをサポートしているか確認
grep -m1 -ow avx /proc/cpuinfo
# 出力が空 → AVX非対応

# CPUモデル名を確認（バグ報告用）
grep -m1 "model name" /proc/cpuinfo

# macOS
sysctl -n machdep.cpu.brand_string

# アーキテクチャを確認
uname -m   # x86_64 / aarch64 / arm64 などを表示

対処: AVX非対応のVPSの場合は別ホスティングに移行するか、Claude Code on the Web（クラウド版）を利用します。アーキテクチャ不一致の場合はGitHub Issuesで報告し、正しいバイナリを再配布してもらいます。

予防策: AWS EC2 や GCP では m5.large 以上の汎用インスタンスは AVX をサポートしています。t2.micro などレガシーなバースト型は AVX 非対応の世代が含まれるため要注意です。

Error loading shared library / glibc・musl 不整合

エラーメッセージ: Error loading shared library libstdc++.so.6: No such file or directory

原因: インストーラーが「musl」ライブラリの環境と誤判定し、glibc 用ではないバイナリをダウンロードしました（あるいはその逆）。glibc 系（Ubuntu/Debian/RHEL）に musl のクロスコンパイル用パッケージが入っているケースで起こりがちです。

解決手順:

# システムのlibcを確認
ldd --version 2>&1 | head -1
# 出力に GNU libc / GLIBC → glibc
# 出力に musl → musl

# Alpine（musl）の場合は依存パッケージを追加
apk add libgcc libstdc++ ripgrep

# glibc なのに musl バイナリが入った場合は一度削除して再インストール
rm -f ~/.local/bin/claude
curl -fsSL https://claude.ai/install.sh | bash

予防策: Alpine Linux などmusl系のディストロでは、Anthropic公式のAlpine Linux setupに従って libgcc libstdc++ ripgrep を追加してください。

dyld: Symbol not found / Abort trap on macOS

エラーメッセージ:

dyld: Symbol not found: _ubrk_clone
  Referenced from: claude-darwin-x64 (which was built for Mac OS X 13.0)
Abort trap: 6

原因: Claude Code のバイナリは macOS 13.0 以上を前提にビルドされています。これより古い macOS では、システムライブラリ（libicucore.A.dylib）に存在しないシンボルを参照してクラッシュします。dyld: cannot load 'claude-...' (load command 0x80000034 is unknown) も同じ原因です。

解決手順:

1. macOSバージョンを確認: Apple メニュー → このMacについて から macOS 13.0 以上か確認
2. macOSを更新: 古い場合はシステム設定 → 一般 → ソフトウェア・アップデートから更新
3. Homebrew経由でも同じバイナリなので回避策にはなりません

予防策: macOS 13未満を使い続ける必要がある場合は、Claude Code on the Web を利用してください。

WSL1 で Exec format error

エラーメッセージ:

claude: cannot execute binary file: Exec format error

このメッセージは GSC ロングテール検索でも観測されており、WSL1 ユーザーが多くつまずく箇所です。

原因: WSL1 のローダーが、Claude Code のネイティブバイナリのプログラムヘッダー変更（Issue #38788）に対応できていません。

解決手順:

最も推奨される対処は WSL2 への変換です。

wsl --set-version <DistroName> 2

どうしても WSL1 を継続したい場合は、動的リンカー経由で呼び出します。

# ~/.bashrc に追記
claude() {
  /lib64/ld-linux-x86-64.so.2 "$(readlink -f "$HOME/.local/bin/claude")" "$@"
}

source ~/.bashrc
claude --version

予防策: WSL2 を標準化する。社内 IT が WSL1 を強制している場合は、本記事のリンクを添えて WSL2 への移行を提案してください。WSL2 はクロスファイルシステム遅延も含めて Claude Code の動作実績が積み重なっています。

Windows: 'irm' is not recognized / '&&' is not valid / 'bash' is not recognized

症状: インストールコマンドをコピペすると、シェル不一致のエラーが返ります。

メッセージ	原因	対処
'irm' is not recognized	CMD で PowerShell コマンドを実行	スタートメニューから PowerShell を起動
The token '&&' is not valid	PowerShell で CMD コマンドを実行	`irm https://claude.ai/install.ps1
'bash' is not recognized	Windows で macOS/Linux コマンドを実行	PowerShell 版インストーラーを使う

解決手順（PowerShell）:

irm https://claude.ai/install.ps1 | iex

解決手順（CMD で完結したい場合）:

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

予防策: ドキュメントを参照するときは、自分のシェルがCMDかPowerShellかを必ず確認します。「Windows ターミナル（Windows Terminal）」のデフォルトプロファイルは PowerShell 7 が推奨です。

Windows: Git for Windows or PowerShell が必須

エラーメッセージ: Claude Code on Windows requires either Git for Windows (for bash) or PowerShell

原因: Claude Code は Windows ネイティブで動作するために Bash（Git for Windows 経由）か PowerShell のいずれかが必要です。両方ともインストールされていないか、PATH に通っていないと起動できません。

解決手順:

1. Git for Windows を git-scm.com/downloads/win からインストール。セットアップ時に「Add to PATH」を選択
2. PowerShell 7 を aka.ms/powershell からインストール
3. Git がインストール済みだが Claude Code が見つけられない場合は ~/.claude/settings.json で明示

{
  "env": {
    "CLAUDE_CODE_GIT_BASH_PATH": "C:\\Program Files\\Git\\bin\\bash.exe"
  }
}

where.exe git で実体パスを確認し、bin\bash.exe を指すように設定します。

Claude Code does not support 32-bit Windows

エラーメッセージ: Claude Code does not support 32-bit Windows

原因: Windows スタートメニューには「Windows PowerShell」と「Windows PowerShell (x86)」の2つが並んでいます。後者の x86 エントリは 32-bit プロセスとして動作するため、64-bit Windows でもこのエラーが出ます。

解決手順:

# 現在の PowerShell が 64-bit OS で動作しているか確認
[Environment]::Is64BitOperatingSystem
# True → OSは64-bit。エラーが出たウィンドウを閉じ、x86 が付かない PowerShell から再実行
# False → OSが32-bit。Claude Code は対応していないため、64-bit版Windowsに更新が必要

予防策: スタートメニューに 2 つの PowerShell が並んでいる場合、必ず「(x86)」が付かない方を起動してください。タスクバーにピン留めすると次回以降の事故を防げます。

Windows: The process cannot access the file

エラーメッセージ: Failed to download binary: The process cannot access the file ... because it is being used by another process

原因: 過去のインストーラーがバックグラウンドで残っているか、ウイルス対策ソフトが %USERPROFILE%\.claude\downloads 内のファイルをスキャンしてロックしています。

解決手順:

# 他の PowerShell ウィンドウを閉じる
# downloads ディレクトリを削除して再実行
Remove-Item -Recurse -Force "$env:USERPROFILE\.claude\downloads"
irm https://claude.ai/install.ps1 | iex

予防策: ウイルス対策ソフトのリアルタイム保護で %USERPROFILE%\.claude\ を一時的に例外指定すると、再発を防げます（インストール完了後は例外を解除）。

Docker でインストールがハング

症状: Dockerfile でインストールを実行するとビルドが進まずハングする

原因: Docker のルートディレクトリ（/）から curl | bash を実行すると、インストーラーがファイルシステム全体をスキャンしてメモリを使い果たします。

解決手順:

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

Docker Desktop ユーザーはメモリ上限を増やします。

docker build --memory=4g .

予防策: Dockerfile では必ず WORKDIR を設定してから Claude Code をインストール。CI/CD では Docker メモリ予算 4GB 以上を確保してください。

Claude Desktop が claude コマンドを乗っ取る

症状: claude を実行すると Claude CLI ではなく Claude Desktop アプリが起動する

原因: 古いバージョンの Claude Desktop が Windows の WindowsApps ディレクトリに Claude.exe を登録し、Claude Code CLI より優先される PATH に配置されています。

解決手順: Claude Desktop を最新版に更新してください。最新版ではこの競合は解消されています。

予防策: where.exe claude で実体パスを確認し、Claude Code CLI が先に来るよう User PATH の順序を整えます。

App unavailable in region

症状: インストール時に HTML が返り、「App unavailable in region」と表示される

原因: お住まいの国・地域では Claude Code が公式提供されていません。

対処: Anthropic の対応国リストを確認してください。VPN 経由での回避は利用規約の観点で推奨されません。代わりにクラウド版 Claude Code（Claude Code on the Web）の対応状況を確認するのが現実的です。

認証・APIキー・組織管理エラー

認証エラーは、Claude Code が API サーバーに対して正しく身元を証明できないときに発生します。/status コマンドで現在の認証方法を確認できます。

ここで重要なのは、ANTHROPIC_API_KEY 環境変数は OAuth ログイン認証より優先されるという挙動です。古い API キーがシェルプロファイルに残っていると、Pro/Max サブスクリプションがあっても無効化された組織のキーが使われ続けます。

Not logged in · Please run /login

エラーメッセージ: Not logged in · Please run /login

原因: 現在のセッションで有効な資格情報が見つかりません。OAuthトークンが保存されておらず、ANTHROPIC_API_KEY も設定されていません。

解決手順:

/login

CI/CD で対話的なログインが不可能な場合は apiKeyHelper を設定します。

{
  "apiKeyHelper": "/path/to/get-claude-key.sh"
}

シェルから直接認証情報を確認する場合:

env | grep -i ANTHROPIC
# Claude Code を起動後、セッション内で /status を実行して認証ソースを確認

予防策: 頻繁にログインを求められる場合はシステムクロックが正確かを確認してください。macOSではKeychainのロックがトークン保存に影響することがあります。

Invalid API Key

エラーメッセージ: Invalid API key · Fix external API key

GSC のロングテール検索でも "invalid api key · fix external api key" が観測されており、本記事に直接流入する代表的な検索クエリです。

原因: ANTHROPIC_API_KEY 環境変数に設定されたキーが無効（タイプミス、取り消し済み、古い形式、組織変更で失効）です。direnv や dotenv プラグインが .env ファイルからキーを読み込み、本人が意識しないまま設定されているケースもあります。

解決手順:

# 現在設定されているキーを確認
env | grep ANTHROPIC

# direnv / dotenv が読み込んでいる可能性をチェック
ls -la .env .envrc 2>/dev/null

# API キーをアンセットしてサブスクリプション認証に切り替え
unset ANTHROPIC_API_KEY
claude

予防策: .env ファイルやシェルプロファイルに古い API キーが残っていないか定期的に確認してください。特に direnv や dotenv プラグインが自動で読み込むケースに注意が必要です。プロジェクトを移動するときは、.envrc に unset ANTHROPIC_API_KEY を明示しておくと事故を防げます。

403 Forbidden

エラーメッセージ: API Error: 403 {"error":{"type":"forbidden","message":"Request not allowed"}}

原因: サブスクリプションが無効、またはアカウントに適切なロールが割り当てられていません。

解決手順:

1. Pro/Max ユーザー: claude.ai/settings でサブスクリプションがアクティブか確認
2. Console ユーザー: アカウントに「Claude Code」または「Developer」ロールがあることを管理者に確認
3. プロキシ環境: 企業プロキシが API リクエストに干渉している可能性があるため、プロキシ設定を確認
4. Bedrock/Vertex/Foundry: クラウド経由で利用している場合は、IAM/サービスアカウントの権限・リージョン設定を再確認

This organization has been disabled

エラーメッセージ: API Error: 400 ... This organization has been disabled

原因: 無効化された組織に紐づく古い ANTHROPIC_API_KEY が、サブスクリプション認証をオーバーライドしています。ANTHROPIC_API_KEY 環境変数は OAuth 認証より優先されるため、シェルプロファイルや .env ファイルに残っている古いキーが原因です。

解決手順:

# 環境変数をアンセット
unset ANTHROPIC_API_KEY

# シェルプロファイルからも削除
# ~/.zshrc や ~/.bashrc で export ANTHROPIC_API_KEY=... の行を削除

# 再起動して確認
claude
/status

/status が Auth: Subscription (Pro) のようにサブスクリプション経由を示せば成功です。

予防策: 退職時・組織変更時には ~/.zshrc ~/.bashrc ~/.profile 内の ANTHROPIC_API_KEY 行を明示的に削除する手順を運用に組み込みます。

Your organization has disabled Claude subscription access

エラーメッセージ: Your organization has disabled Claude subscription access for Claude Code · Use an Anthropic API key instead, or ask your admin to enable access

GSC ロングテール検索でも your organization has disabled claude subscription access for claude code が観測されており、Team/Enterprise プラン導入時に頻発するエラーです。

原因: Claude の組織管理側で「Claude Code でのサブスクリプションログインを禁止」設定が入っています。これはサーバーサイド設定のため、ローカルの環境変数やCLIフラグでは絶対に上書きできません。Agent SDK や非対話モード（-p）では oauth_org_not_allowed というエラーコードで返ります。

解決手順:

1. 管理者に依頼: 組織管理者に Claude Code アクセスを有効化してもらう
2. Console API キーで認証: 個人のサブスクリプションではなく、Anthropic Console で発行したAPIキーを使う

export ANTHROPIC_API_KEY=sk-ant-...
claude

3. 管理者本人が見つけられない場合: claude.ai/admin-settings/claude-code の「Claude Code」「Routines」トグルを確認。それでも該当項目が見当たらない場合はAnthropic サポートに問い合わせ

予防策: 大組織導入時には、初日に「個人サブスクリプションでログインを試みた社員」がこのエラーに遭遇しやすいです。社内アナウンスで「Claude Code は Console API キー or 組織サブスクリプションで利用」と明示しておくとサポート工数を削減できます。

Routines are disabled by your organization's policy

エラーメッセージ: Routines are disabled by your organization's policy.

原因: Team/Enterprise 管理者が組織レベルで「Routines（定期実行ジョブ）」を無効化しています。/schedule コマンド・claude.ai/code の Routines UI・Agent SDK のいずれからも同じエラーが返ります。

解決手順:

1. 管理者にclaude.ai/admin-settings/claude-code の「Routines」トグル有効化を依頼
2. 単発のスケジュール実行で組織ポリシーに抵触しない用途であれば、スケジュールタスク（scheduled tasks）を使う

予防策: Routines を多用するチームでは、組織管理ポリシーで「Routines は許可、ただし監査ログを有効化」の構成を採用。利用ガイドラインも併せて配布します。

OAuth エラーとトークン期限切れ

エラーメッセージ: OAuth token revoked · Please run /login または OAuth token has expired · Please run /login

原因: 保存された OAuth トークンが取り消されたか期限切れになっています。サインアウト全箇所が実行されたか、管理者がアクセス権限を削除したか、自動リフレッシュが失敗しました。

解決手順:

/login

同セッション内で再認証後もエラーが続く場合は、いったん完全ログアウトしてから再ログインしてください。

/logout
/login

頻繁にログインを求められる場合はシステムクロックが正確かを確認します。macOSではKeychainのロックも原因になります。

# macOS: Keychain アクセスを確認
claude doctor

# Keychain をアンロック
security unlock-keychain ~/Library/Keychains/login.keychain-db

予防策: チーム内で「Keychain パスワードと macOS アカウントパスワードの同期がずれている人」を定期的に確認します。Keychain Access の「Edit > Change Password for Keychain "login"」で再同期できます。

OAuth scope requirement

エラーメッセージ: OAuth token does not meet scope requirement: user:profile

原因: 保存されているトークンが、新機能で必要になった権限スコープを持っていません。/usage やステータスラインの使用量表示でよく見られます。

解決手順:

/login

/logout は不要です。/login だけで新しいスコープ付きトークンが発行されます。

予防策: Claude Code のアップデート後にこの種のエラーが出たら、まず /login で更新するのが定石です。

OAuth error: Invalid code

エラーメッセージ: OAuth error: Invalid code. Please make sure the full code was copied

原因: ログインコードの有効期限が切れたか、コピペで途中までしか貼り付けられていません。SSH接続で改行が混ざるケースが典型です。

解決手順:

• ブラウザを開いてからログインを素早く完了する
• ブラウザが自動で開かない場合は c を押して URL をクリップボードにコピー
• リモート/SSH 環境では、URL を手元のブラウザで開き、コードをコピペする

予防策: SSH ターミナルの長いURL改行問題を避けるため、tmux screen の幅を90桁以上に設定するか、claude auth login の標準入力経由でコードを渡します。

OAuth login fails in WSL2 / SSH / コンテナ

症状: Claude Code が WSL2、リモートSSH、コンテナで起動するとブラウザが自動で開かない、または開いてもリダイレクトが localhost に戻らない

原因: Claude Code はローカルコールバックサーバーを起動して OAuth リダイレクトを受け取りますが、別ホストで開いたブラウザからはアクセスできません。

解決手順:

# WSL2: Windows 側のブラウザを指定
export BROWSER="/mnt/c/Program Files/Google/Chrome/Application/chrome.exe"
claude

ブラウザが開けない場合は、対話プロンプトで c を押して URL をコピー、手元のブラウザで開きます。完了後、ログインコードを Paste code here if prompted プロンプトに貼り付けます。

ペーストが効かない場合は次のコマンドで標準入力からコードを受け取れます。

claude auth login

予防策: WSL2 の .bashrc に BROWSER を恒久設定。SSH 多用者は tmux などのバッファ管理ツールを併用すると貼り付けが安定します。

model not found / you may not have access to it

エラーメッセージ: model not found または you may not have access to it

原因: プランで利用できないモデル（Opus など）を指定しているか、ANTHROPIC_MODEL 環境変数で存在しないモデル名が設定されています。

解決手順:

# 現在指定されているモデル名を確認
env | grep ANTHROPIC_MODEL

# 環境変数を解除し、プランの既定モデルを使う
unset ANTHROPIC_MODEL
claude
/model

予防策: Pro プランは Sonnet/Haiku が中心、Max プランで Opus が利用可能になります。プランごとのモデル可用性は Claude Codeの料金プランとレート制限 で整理しています。

Claude Opus is not available with the Claude Pro plan

エラーメッセージ: Claude Opus is not available with the Claude Pro plan · Select a different model in /model

原因: 現在のサブスクリプションプランに Opus が含まれていません。最近 Max プランにアップグレードした場合でも、既存セッションは古いトークンを保持しているため反映されないことがあります。

解決手順:

/model      # 利用可能なモデルを選択
/logout
/login      # プラン情報を最新化

予防策: プランアップグレード直後は /logout → /login を必ず実行する習慣をつけます。プラン別のモデル可用性はclaude.com/pricingで確認してください。

Bedrock / Vertex / Foundry 認証情報が読み込めない

エラーメッセージ:

• Amazon Bedrock: Could not load credentials from any providers
• Google Vertex AI: Could not load the default credentials
• Microsoft Foundry: ChainedTokenCredential authentication failed / CredentialUnavailableError

原因: クラウドプロバイダーのCLIが現在のシェルで認証されていません。あるいはIDE拡張機能の場合、IDEプロセスがシェル環境変数を継承していません。

解決手順:

# Amazon Bedrock
aws sts get-caller-identity   # 認証確認
aws configure                 # 未設定なら初期化

# Google Vertex AI
gcloud auth application-default login
echo "ANTHROPIC_VERTEX_PROJECT_ID=$ANTHROPIC_VERTEX_PROJECT_ID"
echo "CLOUD_ML_REGION=$CLOUD_ML_REGION"

# Microsoft Foundry
az login
echo "ANTHROPIC_FOUNDRY_API_KEY=${ANTHROPIC_FOUNDRY_API_KEY:0:6}..."

IDE 拡張機能で失敗する場合は、IDE 自体の設定でプロバイダー環境変数を設定するか、ターミナルから IDE を起動します。

予防策: クラウド経由運用では ~/.aws/credentials や Application Default Credentials の更新タイミングを CI/CD のチェック対象に含めます。詳細はAmazon Bedrock、Google Vertex AI、Microsoft Foundry の各セットアップを参照してください。

レート制限・使用量系エラー

レート制限エラーは、使用量がアカウントやプランの上限に達したときに発生します。重要なのは、4種類の制限が存在することを理解することです。

制限の種類	対象	エラーメッセージ	リセット
セッション制限	Pro/Max サブスク	You've hit your session limit · resets 3:45pm	初回リクエストから5時間後
週間制限	Pro/Max サブスク	You've hit your weekly limit	ローリング7日間でリセット
Opus制限	Pro/Max サブスク	You've hit your Opus limit · resets 3:45pm	モデル別5時間
API 制限（RPM/TPM）	API キー	Request rejected (429)	数秒〜数分で自動リセット

セッション・週間制限（サブスクリプション）

エラーメッセージ: You've hit your session limit · resets 3:45pm または You've hit your weekly limit または You've hit your Opus limit · resets ...

原因: Pro/Max プランは2段階の使用量管理を採用しています。Anthropic の公式ヘルプセンターによれば、5時間のセッション枠は最初のリクエストを送信した時点でカウントが始まり、それと並行して全モデル横断の週次クォータが消費されます（出典: Use Claude Code with your Pro or Max plan - Claude Help Center）。

2026年に入り、ピーク時間帯にセッション制限へ到達しやすい挙動がユーザー報告として上がっており、エラーメッセージが表示されないまま処理が止まるケースもあるようです（ユーザー報告: anthropics/claude-code Issue #38335、Anthropic 公式アナウンスではありません）。

解決手順:

1. /usage で現在の使用状況とリセット時刻を確認
2. リセット時刻まで待機するか、/model sonnet や /model haiku で軽量モデルに切り替えて作業を継続
3. claude.ai/settings/usage のプログレスバーで5時間/週間の両方の残量を確認
4. Pro/Max プランでは /usage-credits から追加使用量を購入可能（出典: Extra usage for paid Claude plans - Support Center）

予防策: /cost でセッション中の使用量を定期的に確認し、大きなタスク開始前に /status で残量を把握してください。/compact で会話を圧縮すれば、同じセッション枠でより多くの作業を実行できます。

Server is temporarily limiting requests

エラーメッセージ: API Error: Server is temporarily limiting requests (not your usage limit)

原因: API側が一時的に短時間のスロットルを適用しています。アカウントのクォータとは無関係です。自動リトライが10回まで実施された後にこのエラーが表示されます。

解決手順:

1. 数十秒〜数分待ってから再試行
2. 続く場合は status.claude.com でインシデント情報を確認

API 429 Rate limit reached

エラーメッセージ: API Error: 429 Rate limit reached または Request rejected (429) · this may be a temporary capacity issue

原因: API キー認証で利用している場合のリクエスト/分（RPM）、入力トークン/分（ITPM）、出力トークン/分（OTPM）、または1日あたりの支出制限のいずれかに到達しています。Bedrock や Vertex AI 経由の場合、それぞれのプロバイダー側でも独立した制限が適用されます。

解決手順:

1. /status で現在の認証ソースを確認。意図しない ANTHROPIC_API_KEY が低ティアキーを参照していないか
2. /cost を実行し、現在のセッションの累積使用量を確認
3. platform.claude.com/console でアカウントの RPM/TPM 設定とプラン階層を確認
4. リトライ実装には指数バックオフ + ジッターを使用（最初の待機は2-4秒、その後は倍々で増加）
5. 並列度を下げる: CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY を低めに設定、サブエージェントの大量並列起動を避ける、/model haiku などへの切替も検討

指数バックオフの実装例（Node.js）:

async function callWithRetry(fn, maxRetries = 5) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (e) {
      if (e.status !== 429) throw e;
      const delay = Math.min(2 ** i * 1000 + Math.random() * 1000, 30000);
      await new Promise(r => setTimeout(r, delay));
    }
  }
  throw new Error('Max retries reached');
}

予防策: バッチ処理では並列度（concurrency）を調整し、Claude が返す retry-after ヘッダーを尊重してください。Claude API のレート制限の詳細は Rate limits - Claude API Docs に整理されています。

529 Overloaded（サーバー過負荷）

エラーメッセージ: API Error: Repeated 529 Overloaded errors · check status.claude.com

原因: API サーバー全体が一時的に容量に達しています。529 はアカウントのクォータとは無関係です。

解決手順:

1. status.claude.com でインシデント情報を確認
2. 数分待ってから再試行
3. /model で別のモデルに切り替え（モデルごとに容量が管理されているため）

Claude Code が Opus is experiencing high load, please use /model to switch to Sonnet のような切替を促すメッセージを出した場合は素直に従うのが最短ルートです。

Credit balance is too low

エラーメッセージ: Credit balance is too low

原因: API Console 組織のプリペイドクレジットが不足しています。

解決手順:

1. platform.claude.com/settings/billing でクレジットを追加。同画面で自動リロードを有効化しておくと残高ゼロ前に補充される
2. Pro/Max プランがある場合は /login でサブスクリプション認証に切り替え
3. ワークスペース単位の支出上限を Console で設定し、特定プロジェクトの暴走を防止

予防策: API Console 設定で自動リロード閾値を設定しておくと、作業中にクレジット切れで中断されることを防げます。コスト管理の詳細はManage costs effectivelyも参照してください。

コンテキスト・メモリ系エラー

コンテキストエラーは、会話の蓄積やファイルの添付によりモデルのコンテキストウィンドウが限界に達したときに発生します。Claude Codeのコンテキスト・メモリ管理 では /compact、/clear、サブエージェントの使い分けを詳しく解説しています。

Prompt is too long

エラーメッセージ: Prompt is too long

原因: 会話履歴、システムプロンプト、ツール定義、添付ファイルの合計がモデルのコンテキストウィンドウを超えています。

解決手順:

# 1. コンテキストを要約して圧縮
/compact

# 2. 特定の情報だけ残して圧縮（推奨）
/compact keep only the plan and the diff

# 3. 完全にリセットして新しいセッションを開始
/clear

# 4. コンテキストの内訳を確認
/context

予防策:

• 自動コンパクトはデフォルトで有効です。DISABLE_AUTO_COMPACT 環境変数を設定している場合は再度有効にしてください
• 使用していない MCP サーバーは /mcp disable <name> で無効化し、ツール定義によるコンテキスト消費を削減してください
• 大きなファイルはパスで参照し、内容を直接貼り付けないようにしましょう
• CLAUDE.md メモリファイルが肥大化していないか確認。/doctor がサイズ過大を検出します

Autocompact is thrashing

エラーメッセージ: Autocompact is thrashing: the context refilled to the limit...

GSC ロングテール検索でも autocompact is thrashing が観測されており、本記事に直接流入する代表クエリです。

原因: 自動コンパクションは成功したものの、大きなファイルやツール出力がコンテキストウィンドウを連続で満杯に戻しています。Claude Code は無駄な API 呼び出しを止めるために再試行を停止します（出典: Claude Code Docs - トラブルシューティング）。

解決手順:

1. 大きなファイルを行範囲で読む: ファイル全体ではなく、特定の関数や行範囲（例: lines 200-300）に絞って読むよう指示
2. focus 引数付きの /compact: 例 /compact keep only the plan and the diff のように、保持したい情報を明示
3. サブエージェントに分離: 大規模ファイル処理はサブエージェントに委任すれば、別のコンテキストウィンドウで実行される
4. /clear で新セッション: 過去の会話が不要な場合は完全リセットが最速

Error during compaction: Conversation too long

エラーメッセージ: Error during compaction: Conversation too long. Press esc twice to go up a few messages and try again.

原因: /compact 自体が失敗しています。コンテキストウィンドウに「要約結果を書き込むだけの空き」が残っていないか、Prompt is too long が出た直後に /compact を試みた場合に発生します。

解決手順:

1. Esc を2回押す: メッセージリストを開き、数ターン前まで巻き戻す
2. その状態で /compact を再実行
3. それでも空きが足りなければ /clear で新セッションを開始（claude --resume で再開可能）

予防策: /context を定期的に確認し、80%を超える前に手動 /compact を実行する習慣をつけます。

Request too large (max 30 MB)

エラーメッセージ: Request too large (max 30 MB)

原因: コンテキストウィンドウの制限とは別に、HTTP リクエスト自体のバイトサイズ制限（30MB）を超えています。大きなファイルの貼り付けが原因です。

解決手順: Esc キーを2回押して、サイズ超過の原因となったターンに戻ってください。大きなファイルは貼り付けではなくパスで参照し、Claude にチャンク単位で読み取らせてください。

Image was too large

エラーメッセージ: Image was too large. Double press esc to go back and try again with a smaller image. または API Error: 400 ... image dimensions exceed max allowed size

原因: 添付した画像がAPIのサイズ制限・解像度制限を超えています。単独画像で長辺8000ピクセル、複数画像時は2000ピクセルが上限です。画像はエラー後も会話履歴に残り続けるため、次のメッセージも同じエラーで失敗し続けます。

解決手順:

1. Esc キーを 2 回押して、画像を添付したターンの前まで巻き戻す
2. 解像度を下げて再添付（必要部分のみのスクリーンショットが推奨）
3. デザインカンプなど大きな画像はパス参照と Read ツール経由に切り替え

予防策: スクリーンショットは「全画面」ではなく「対象部分のみ」に絞ります。デザインツールから書き出す画像は事前に長辺を 2000px 以下にリサイズしておきます。

PDF too large / password protected / not valid

エラーメッセージ:

PDF too large (max 100 pages, 32 MB). Try splitting it or extracting text first.
PDF is password protected. Try removing protection or extracting text first.
The PDF file was not valid. Try converting to a different format first.

原因: Claude API の PDF アップロード制限（100ページ・32MB）超過、パスワード保護、ファイル破損。

解決手順:

# テキスト抽出してから渡す
pdftotext input.pdf output.txt
# または Claude に Read ツールで部分読み取りを依頼

# パスワード解除（qpdf）
qpdf --password=<pw> --decrypt input.pdf output.pdf

または PDF を「ページ範囲指定で読む」よう Claude に指示します。

予防策: 大規模PDFは ETL 段階でテキスト抽出して .txt として保存。Claude へは抽出済みファイルをパス参照で渡すと安定します。

Auto mode classifier transcript exceeded context window

エラーメッセージ: Auto mode classifier transcript exceeded context window — falling back to manual approval (try /compact to reduce conversation size)

原因: auto mode で使用される分類モデルのコンテキストウィンドウを会話全体のサイズが超過しました。対話セッションでは通常の承認プロンプトにフォールバックしますが、非対話モード（-p）では実行が中断されます。

解決手順:

1. 表示される承認プロンプトで y または n を選んで個別承認
2. /compact で会話サイズを減らす
3. 非対話モード（CI/CD など）では事前に分割して短いプロンプトに

Extra inputs are not permitted（gateway header strip）

エラーメッセージ:

API Error: 400 ... Extra inputs are not permitted ... context_management
API Error: 400 ... Extra inputs are not permitted ... tools.0.custom.input_examples
API Error: 400 ... Unexpected value(s) for the `anthropic-beta` header

原因: LLM ゲートウェイやプロキシが anthropic-beta ヘッダーを除去してしまい、ベータ機能依存のフィールドだけが残った結果、API がリクエストを拒否します。

解決手順:

1. ゲートウェイ側で anthropic-beta ヘッダーをそのまま転送する設定にする（参考: LLM gateway configuration）
2. それが不可能な場合は、Claude Code 側でベータ機能を無効化

export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1

予防策: LLM gateway を構築・運用する際は、Anthropic 由来のヘッダーをすべてホワイトリスト方式で透過設定にします。

/heapdump でメモリリーク解析

コンテキストエラーとは別に、JavaScript ヒープの肥大化が原因で Claude Code 全体が重くなることがあります。/heapdump コマンドで JS ヒープスナップショットを取得し、Chrome DevTools で解析できます。

/heapdump
# → ~/Desktop/heapdump-YYYYMMDD-HHMMSS.heapsnapshot に書き出される

Chrome DevTools の [Memory] タブ → [Load profile] からスナップショットを開き、リテイナーツリーでメモリを保持しているオブジェクトを特定します。常駐セットサイズと JS ヒープを比較し、JavaScript 側ではなくネイティブメモリが肥大化している場合は GitHub の anthropics/claude-code Issues にスナップショットを添付して報告すると改善につながります。

MCP接続エラーの体系的デバッグ

MCP（Model Context Protocol）は外部ツールとの連携を可能にする仕組みですが、設定ミスが起きやすい箇所でもあります。Claude CodeのMCP統合 で基本設定を確認した上で、本セクションのデバッグ手順を試してください。

Could not connect to MCP server

エラーメッセージ: Could not connect to MCP server または Connection closed

原因: MCP サーバーの起動に失敗しているか、接続が確立できていません。

MCP デバッグログのパス

エラーメッセージが曖昧な場合、まず MCP のログファイルを直接確認するのが最短です。OS 別の保存先は以下の通りです。

OS	ログディレクトリ
macOS	~/Library/Logs/Claude/
Windows	%APPDATA%\Claude\logs\
Linux	~/.config/Claude/logs/

ログファイルは MCP サーバーごとに分かれて出力されます。サーバー名でフィルタすると目当てのログにすぐ到達できます。

# macOS の例: 過去1時間以内に更新された MCP ログだけを一覧
ls -lt ~/Library/Logs/Claude/mcp-*.log | head
tail -n 200 ~/Library/Logs/Claude/mcp-my-server.log

デバッグ手順

ステップ1: claude mcp list で接続状態を確認

claude mcp list

接続が確立できているサーバーは connected、起動に失敗しているサーバーは failed (exit code X) のように表示されます。

ステップ2: .mcp.json 設定の検証

# プロジェクトの .mcp.json を確認
cat .mcp.json

# ユーザー全体の設定を確認
cat ~/.claude/settings.json

確認ポイント:

• コマンドのパスが正しいか（相対パスではなくフルパスを推奨）
• サーバー名が英数字・アンダースコア・ハイフンのみで1〜64文字以内か
• JSON 構文にエラーがないか
• disabled: true フラグが意図せず付いていないか
• API キーのプレースホルダ（YOUR_API_KEY 等）が残っていないか

ステップ3: コマンドの実行確認

# MCP サーバーのコマンドが直接実行できるか確認
which npx     # または which uvx
npx --version

Python ベースのサーバーで uvx が見つからない場合:

# uv をインストール
pip install uv

ステップ4: 環境変数の継承問題（特に NVM/asdf 環境）

Claude Code を GUI ターミナル（Terminal.app など）から起動した場合、シェルの .zshrc が読まれない環境変数があり、NVM や asdf で管理している node のパスが見つからないケースがあります。.mcp.json 内で明示的に env を指定するか、command にフルパスを書きます。

{
  "mcpServers": {
    "my-server": {
      "command": "/Users/me/.nvm/versions/node/v22.0.0/bin/npx",
      "args": ["-y", "my-mcp-server"],
      "env": {
        "PATH": "/usr/local/bin:/usr/bin:/bin",
        "API_KEY": "your-api-key-here"
      }
    }
  }
}

ステップ5: Windows 環境での注意

Windows 環境では、npx を使用する MCP サーバーに cmd /c ラッパーが必要な場合があります:

{
  "mcpServers": {
    "my-server": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "my-mcp-server"]
    }
  }
}

ステップ6: サブエージェントへのMCPツール継承

サブエージェントは親セッションのMCPツール定義をすべて継承します。これがサブエージェント起動直後のコンテキストを圧迫し、Prompt is too long の遠因になります。サブエージェントを多用する場合は、用途外のMCPサーバーを /mcp disable <name> で事前に無効化してください。

MCP ツールが認識されない（エラーなし）

症状: エラーメッセージは出ないが、/mcp を実行しても期待したサーバーが表示されない、またはツールが Claude から見えない。

原因と対処:

1. 設定ファイルの場所違い: プロジェクトの .mcp.json とユーザーの ~/.claude/settings.json のどちらに書いたかを再確認
2. サーバー名の重複: 同名のサーバーが複数の設定ファイルに存在すると後者が無視される場合がある
3. disabled: true フラグ: 設定ファイル内で明示的に無効化されていないか確認
4. API キーのプレースホルダ: YOUR_API_KEY のようなダミー値が残ったままになっていないか確認
5. サーバー名制約違反: 大文字・スペース・記号は使えない

予防策: MCP サーバーを追加する際は、claude mcp add コマンドを使うと設定ミスを減らせます。/doctor を実行すれば、MCP サーバーの接続状態を一括確認できます。

モデル選定・thinking budget エラー

モデル指定とExtended Thinkingの設定に関するエラーは、CLIアップグレード後や複数のClaude Code環境を切り替える運用で発生しがちです。

There's an issue with the selected model

エラーメッセージ: There's an issue with the selected model (claude-...). It may not exist or you may not have access to it. Run /model to select a different one.

原因: 指定したモデルIDが認識されないか、現在のアカウントでアクセス権がありません。--model フラグ、ANTHROPIC_MODEL 環境変数、.claude/settings.local.json、プロジェクトの .claude/settings.json、~/.claude/settings.json のいずれかに古いIDが残っているケースが大半です。

解決手順:

/model              # 利用可能なモデルから選択

# 環境変数から古いIDを除去
unset ANTHROPIC_MODEL

エイリアス（sonnet / opus）を使うと最新版を自動追従できます（フルバージョンIDは更新後に陳腐化）。

予防策: チームで利用する .claude/settings.json は「model: sonnet」のようにエイリアスで揃え、特定バージョンへのピン留めはCIなど明示的に必要な場面に限定します。

thinking.type.enabled is not supported for this model

エラーメッセージ: API Error: 400 ... "thinking.type.enabled" is not supported for this model. Use "thinking.type.adaptive" and "output_config.effort" to control thinking behavior.

原因: Claude Code が Opus 4.7 の最低要件（v2.1.111 以降）を満たしていません。旧バージョンが現在は廃止された thinking.type.enabled フィールドを送信しています。

解決手順:

claude update
# v2.1.111 以降であることを確認
claude --version

更新できない環境では /model で Opus 4.6 または Sonnet にダウングレードします。

Thinking budget exceeds output limit

エラーメッセージ: API Error: 400 ... max_tokens must be greater than thinking.budget_tokens

原因: MAX_THINKING_TOKENS が、現在のプロバイダーの出力上限を超えています。Amazon Bedrock や Google Vertex AI で発生しがちで、特に Plan モードで thinking budget が引き上げられた場合に顕在化します。

解決手順:

# MAX_THINKING_TOKENS を下げる
unset MAX_THINKING_TOKENS
# または明示的に低めに
export MAX_THINKING_TOKENS=16000

# CLAUDE_CODE_MAX_OUTPUT_TOKENS を上げる
export CLAUDE_CODE_MAX_OUTPUT_TOKENS=64000

予防策: Bedrock/Vertex 利用時は、プロバイダー側の出力上限を確認した上で MAX_THINKING_TOKENS を設定してください。

Tool use or thinking block mismatch

エラーメッセージ:

API Error: 400 due to tool use concurrency issues. Run /rewind to recover the conversation.
API Error: 400 ... unexpected `tool_use_id` found in `tool_result` blocks
API Error: 400 ... thinking blocks ... cannot be modified

原因: ツール呼び出しの途中で中断したり、ストリーミング中にターンを編集したことで、tool_use / tool_result / thinking のブロック列が API の期待する形式と食い違いました。

解決手順:

/rewind

または Esc キーを 2 回押して、破損したターンより前のチェックポイントへ戻ります。詳細はCheckpointingを参照してください。

Responses seem lower quality than usual チェックリスト

エラーは出ていないが「Claudeが雑になった」と感じた場合の4ステップチェックリストです（出典: Error reference - Claude Code Docs）。

1. /model — 期待したモデルが選択されているか
2. /effort — 推論努力レベル（reasoning effort）が必要な高さか
3. /context — コンテキストが満杯に近づいていないか
4. /doctor — 肥大化した CLAUDE.md や MCP ツール定義が品質を引っ張っていないか

パフォーマンス・安定性のトラブル

以下の問題はエラーメッセージが表示されないケースです。症状から対処法を確認してください。

CPU/メモリ使用量が高い

症状: Claude Code のプロセスが CPU やメモリを大量に消費している

原因と対処:

1. コンテキストの肥大化: /compact でコンテキストを圧縮
2. 大規模ビルドディレクトリ: .gitignore に node_modules、dist、build、.next などを追加。Claude Code は .gitignore を尊重し、検索対象から除外する
3. 長時間セッション: 主要なタスク間で Claude Code を閉じて再起動

メモリ使用量が改善しない場合は、前述の /heapdump でヒープスナップショットを取得し、JavaScript ヒープが原因か、ネイティブメモリが原因かを切り分けてください。

ハング・フリーズ

症状: Claude Code が応答しない、または極端に遅い

解決手順:

# 1. Ctrl+C で現在の操作をキャンセル
# 2. 応答しない場合はターミナルを閉じて再起動
# 3. セッションを再開（会話は失われない）
claude --resume

Worker クラッシュ（Worker started ログ多発）

症状: 動作中に応答が遅くなり、ターミナルに Worker started というログが何度も繰り返し出力される

原因: Claude Code のバックグラウンドプロセス（Worker）が静かにクラッシュ→再起動を繰り返している状態です。claude-mem のような実験的拡張機能や、巨大な SQLite データベースを参照する MCP サーバーが原因で、Worker が継続的に落ちるケースが報告されています。Worker started が1〜2回出るのは正常ですが、10回、20回と連続するのは異常です。

解決手順:

1. 実験的な拡張機能（claude-mem など）を一時的に無効化して再起動
2. ~/.claude/settings.json で experiments セクションを確認し、不要な機能をオフにする
3. /doctor で MCP サーバーの稼働状況を確認し、応答が遅いサーバーを /mcp disable で停止
4. それでも改善しない場合は /heapdump を取得し、GitHub Issues に添付して報告

検索ツールがファイルを見つけられない / USE_BUILTIN_RIPGREP=0

症状: Search ツール、@file メンション、カスタムエージェントがファイルを見つけられない、または検索結果が不完全

原因: バンドルされた ripgrep バイナリがシステムで実行できない、または速度が出ないケースがあります。USE_BUILTIN_RIPGREP=0 を設定すると、システムにインストールされた ripgrep を使うようになり、大規模コードベースで5〜10倍高速化したという報告があります（出典: terrylica/cc-skills Issue #3 - Performance: Enable 5-10x Faster Grep with System Ripgrep）。

解決手順:

# macOS
brew install ripgrep

# Ubuntu/Debian
sudo apt install ripgrep

# Alpine
apk add ripgrep

# Windows
winget install BurntSushi.ripgrep.MSVC

その後、シェルプロファイルに環境変数を追加します（カレントセッションのみの export だと再起動で失われるため、必ず rc ファイルに書き込んでください）。

echo 'export USE_BUILTIN_RIPGREP=0' >> ~/.zshrc
source ~/.zshrc

USE_BUILTIN_RIPGREP=0 を ~/.claude/settings.json に書いても、現状の実装では一部のケースで反映されないバグが報告されています（参考: anthropics/claude-code Issue #6415）。シェル rc に書く方式が確実です。

WSL でファイル検索が遅い・不完全

症状: WSL 環境で Search ツールがネイティブより少ない結果しか返さない、または極端に遅い

原因: WSL のクロスファイルシステム（Windows 側 /mnt/c/ ↔ Linux 側 /home/）にはディスク読み取りのペナルティがあり、これが検索速度に直結します。

解決手順:

1. より具体的な検索: ディレクトリやファイルタイプを絞る（例: 「auth-service パッケージで JWT 検証ロジックを検索」）
2. プロジェクトを Linux ファイルシステムに移動: /mnt/c/Users/me/project から /home/me/project へ移動
3. ネイティブ Windows 版を使う: WSL ではなく Windows ネイティブの Claude Code を試す

Auto mode cannot determine the safety of an action

エラーメッセージ:

• <model> is temporarily unavailable, so auto mode cannot determine the safety of <tool> right now.
• Auto mode could not evaluate this action and is blocking it for safety — run with --debug for details

原因: auto mode で利用される分類モデルが、過負荷・応答不能・出力解析失敗のいずれかで判定を完了できませんでした。読み取り・検索・カレントディレクトリ内の編集は分類器をスキップするため動作を継続します。

解決手順:

1. 数秒待って再試行
2. claude --debug で再度同じアクションを実行し、デバッグログから分類モデルの応答を確認
3. 設定変更は不要。一時的なものなので auto mode の利用条件は変えなくてよい

「Claudeが雑になった」と感じたら（thinking budget）

症状: エラーは出ないが、回答の品質が低下しているように感じる

前提知識（2026年版）: かつて Claude Code には /think、think hard、ultrathink といった思考時間を増やすキーワードが存在しましたが、自動 Extended Thinking が default になったことで ultrathink キーワードは deprecated となりました（出典: UltraThink is Dead. Long Live Extended Thinking. - Decode Claude）。現在はモデルが必要に応じて自動で思考トークンを割り当てます。

チェックリスト:

1. モデルを確認: /model を実行し、意図したモデル（Opus / Sonnet / Haiku）が選択されているか確認。ANTHROPIC_MODEL 環境変数が小さなモデルを指定していないか
2. MAX_THINKING_TOKENS を確認: 環境変数 MAX_THINKING_TOKENS が低い値で設定されていると、自動 Extended Thinking が制限される。デフォルトは 31,999 トークン、設定可能範囲は 1,024〜200,000（出典: Model configuration - Claude Code Docs）
3. コンテキスト圧力を確認: /context でコンテキストウィンドウの使用状況を確認。容量に近い場合は /compact を実行
4. 巻き戻し: 品質の低い回答が出た場合、修正で返信するより Esc キーを2回押して巻き戻す方が効果的

MAX_THINKING_TOKENS の確認と調整:

# 現在の設定を確認
env | grep MAX_THINKING_TOKENS

# 抑制している設定を一時解除
unset MAX_THINKING_TOKENS

MAX_THINKING_TOKENS が設定されていると、ultrathink のような特定の思考キーワードが「環境変数による上限」に上書きされて無視されるという既知の挙動があります（参考: anthropics/claude-code Issue #18072）。コストを抑えたい場合のみ意図的に下げ、デバッグや設計タスクではアンセットするのが安全です。

IDE 統合のトラブル

IDE 統合のトラブルは、VS Code や JetBrains 拡張から Claude Code を呼び出す際のプロセス連携・環境変数継承・ネットワーク許可で発生します。多くは IDE 自体を再起動するか、拡張機能を最新版に保つことで解消します。

VS Code 拡張機能の応答なし問題

症状: Claude Code for VS Code が更新アイコンが表示されたまま応答しない

解決手順:

1. VS Code のコマンドパレット（Cmd+Shift+P / Ctrl+Shift+P）を開く
2. 「Claude Code: Restart」を実行
3. 改善しない場合は拡張機能を無効化→再有効化
4. それでも改善しない場合は拡張機能のバージョンをダウングレード

予防策: VS Code 自体と Claude Code 拡張機能を最新バージョンに保ってください。IDE 拡張から Bedrock/Vertex/Foundry を利用する場合は、IDE のプロセスがシェル環境変数を継承していない可能性があるため、IDE 設定で明示的に環境変数を設定するか、ターミナルから IDE を起動します。

JetBrains プラグインの検出問題

症状: No available IDEs detected エラーが表示される

原因: WSL2 環境でのネットワーク設定または Windows ファイアウォールによるブロックが原因の場合があります。

解決手順:

1. JetBrains IDE が起動していることを確認
2. ファイアウォール設定で JetBrains IDE の通信を許可
3. WSL2 環境の場合はネットワーク設定を確認
4. プラグインバージョンを公式マーケットプレイスから再インストール

ネットワーク・環境別トラブル

ネットワーク・環境別トラブルは、企業プロキシ・VPN・DNS・クラウドサンドボックスのいずれかが Claude Code の outbound 通信に干渉して発生します。インターネット接続自体が問題なく、別アプリの通信が成立している場合でも、Claude Code 固有のホスト・ヘッダー・証明書要件によりブロックされるケースが多いです。

Unable to connect to API

エラーメッセージ: Unable to connect to API. Check your internet connection や ECONNREFUSED、ECONNRESET、ETIMEDOUT、fetch failed、Request timed out. Check your internet connection and proxy settings

原因: インターネット接続の問題、VPN によるブロック、または企業プロキシの設定不備、DNS不整合、Docker Desktop による outbound interception など多岐にわたります。

解決手順:

# API サーバーへの接続を確認
curl -I https://api.anthropic.com

# Windows PowerShell では curl.exe を明示
curl.exe -I https://api.anthropic.com

# 企業プロキシ環境の場合
export HTTPS_PROXY=http://proxy.example.com:8080
claude

curl は成功するが Claude Code は失敗する場合は、ローカル要因を確認します。

• Linux/WSL: /etc/resolv.conf に到達不能なネームサーバーが残っていないか。cat /etc/resolv.conf で確認
• macOS: VPN クライアントを切断・アンインストールした後の utun インターフェース残骸。ifconfig | grep utun で確認、不要なら System Settings → ネットワーク → VPN拡張から削除
• Docker Desktop: outbound traffic を傍受している可能性。Docker Desktop を一時停止して再試行

予防策: 企業環境では、IT 部門に Claude Code がアクセスするホストのホワイトリスト登録を依頼してください。ネットワーク設定の詳細も参照してください。

SSL 証明書エラー（企業環境）

エラーメッセージ: Unable to connect to API: SSL certificate verification failed や Self-signed certificate detected

原因: 企業のプロキシやセキュリティアプライアンスが TLS 通信をインターセプトしており、その証明書が Node.js に信頼されていません。インストール時の TLS/SSL エラーについては「インストール・セットアップ系エラー」セクションの TLS/SSL エラーも参照してください。

解決手順:

# 企業の CA 証明書を Node.js に認識させる
export NODE_EXTRA_CA_CERTS=/path/to/ca-bundle.pem

NODE_TLS_REJECT_UNAUTHORIZED=0 は証明書検証を完全に無効にするため、絶対に設定しないでください。中間者攻撃（MITM）に対し無防備になり、API キーや会話内容が傍受されるリスクがあります。

Host not allowed in a cloud session

エラーメッセージ:

HTTP 403
x-deny-reason: host_not_allowed

原因: Claude Code on the Web や Routines の cloud session は、サンドボックス環境で動作しており、outbound 通信が Default 環境の許可ドメイン（パッケージレジストリ・主要クラウドプロバイダAPI等）に限定されています。これ以外のドメインにアクセスするとブロックされます。

解決手順:

1. Routine を編集画面で開く、または cloud session を起動
2. 環境名（例: Default）のクラウドアイコン → 設定アイコン
3. Update cloud environment ダイアログで Network access を Trusted から Custom に変更
4. Allowed domains にアクセスしたいドメインを1行ずつ追加
5. 「Also include default list of common package managers」を有効化したまま保存
6. 全許可が必要なら Full を選択

予防策: Routine ごとに必要なドメインを最小限で明示するのがセキュリティ上望ましいです。詳細はClaude Code on the Web の Network access。

Usage Policy refusal

エラーメッセージ: Claude Code is unable to respond to this request, which appears to violate our Usage Policy (https://www.anthropic.com/legal/aup)

原因: 会話全体の内容がAnthropic Usage Policyのチェックに抵触しました。直近のプロンプトだけでなく、会話履歴全体が評価されるため、新メッセージを送っても同じ refusal が再発します。

解決手順:

1. Esc を2回押す または /rewind で、refusal を引き起こしたターンより前のチェックポイントへ戻る
2. 別のアプローチで再質問
3. --continue や --resume で同セッションを再開しても、ディスク上の履歴に refusal トリガーが残っているため再発する。/clear で新セッションを開始する

予防策: 誤判定だと感じる場合は、エラーメッセージに含まれる Request ID をAnthropic サポートに伝えて確認を依頼してください。

Bedrock / Vertex AI / Foundry 経由運用の注意点

クラウド経由で Claude Code を利用する場合、ネットワーク・認証・モデル可用性の3点で独自のエラーが発生しやすくなります。

項目	Bedrock	Vertex AI	Foundry
認証コマンド	aws sts get-caller-identity	gcloud auth application-default login	az login
必須環境変数	AWS_REGION 等	ANTHROPIC_VERTEX_PROJECT_ID / CLOUD_ML_REGION	ANTHROPIC_FOUNDRY_API_KEY
モデル可用性	リージョン別、ARN指定	リージョン別、Endpoint指定	デプロイ単位
429 の発生源	Bedrock サービスクォータ	Vertex AI APIクォータ	Foundry レート制限
ステータスページ	AWS Health Dashboard	GCP Status	Azure Status

トラブル時のチェック手順は次の通りです。

1. 認証コマンドが成功するか: 上記表の認証確認コマンドを実行
2. 環境変数が現在のシェルで露出しているか: env | grep ANTHROPIC_VERTEX などで確認
3. モデル名・リージョンが正しいか: /model で利用可能なモデル、プロバイダーコンソールでリージョン × モデルの組み合わせ
4. IDE 拡張機能の場合: ターミナルから IDE を起動するか、IDE 設定でプロバイダー環境変数を明示

詳細はAmazon Bedrock、Google Vertex AI、Microsoft Foundryの各セットアップガイドを参照してください。

Claude Code 環境変数リファレンス

Claude Code の挙動はいくつかの環境変数で制御できます。本記事で扱った主な変数を16項目に拡張しました。

環境変数	デフォルト	用途	関連エラー / セクション
ANTHROPIC_API_KEY	-	API キー認証	Invalid API key / organization disabled
ANTHROPIC_MODEL	-	既定モデルの指定	model not found / thinking budget
ANTHROPIC_BASE_URL	-	LLM gateway / リレーサーバー	API 接続不可
ANTHROPIC_CUSTOM_HEADERS	-	プロキシ環境向け追加ヘッダー	企業ネットワーク
MAX_THINKING_TOKENS	31999	Extended Thinking の上限（範囲 1024-200000）	thinking budget / thinking budget exceeds
USE_BUILTIN_RIPGREP	1	バンドル ripgrep の使用切替（0 で OS の ripgrep）	ripgrep
NODE_EXTRA_CA_CERTS	-	企業 CA 証明書の追加	TLS/SSL / SSL（実行時）
DISABLE_AUTO_COMPACT	-	自動コンパクトの無効化	Prompt too long
HTTPS_PROXY / HTTP_PROXY	-	プロキシ経由の通信	API 接続不可
CLAUDE_CODE_MAX_RETRIES	10	自動リトライ回数	Server limit / 529
API_TIMEOUT_MS	600000	リクエストタイムアウト (ms)	Request timed out
CLAUDE_CODE_MAX_OUTPUT_TOKENS	-	出力トークン上限	thinking budget exceeds
CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY	-	ツール並列度の上限	API 429
CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS	-	ベータ機能を停止（gateway互換性）	Extra inputs
CLAUDE_CODE_GIT_BASH_PATH	-	Windows での Git Bash パス	Git for Windows
BROWSER	-	WSL/SSH での OAuth ブラウザ	WSL OAuth

設定方法:

# シェル rc ファイルに永続化（推奨）
echo 'export USE_BUILTIN_RIPGREP=0' >> ~/.zshrc
source ~/.zshrc

~/.claude/settings.json の env セクションにも書けますが、一部の環境変数（USE_BUILTIN_RIPGREP など）は反映されないバグがあるため、シェル rc に書く方が確実です。

再発防止チェックリスト

エラーを解決した後、同じ問題を二度と踏まないための運用上の対策です。

環境変数の永続化（シェル rc）

# 必要な環境変数を ~/.zshrc または ~/.bashrc に書き込む
cat <<'EOF' >> ~/.zshrc
# Claude Code 環境設定（企業環境向け）
export NODE_EXTRA_CA_CERTS=/path/to/ca-bundle.pem
export HTTPS_PROXY=http://proxy.example.com:8080
export USE_BUILTIN_RIPGREP=0
# ANTHROPIC_API_KEY を unset しておくとサブスクリプション優先
unset ANTHROPIC_API_KEY
EOF
source ~/.zshrc

APIキーの安全な扱い（重要）

ANTHROPIC_API_KEY を ~/.zshrc ~/.bashrc .env などに平文で書き込むのは避けてください。dotfiles を Git 管理している場合は GitHub 公開リポジトリに流出する事故、自動バックアップやチャットでのスクリーンショットでの露出、退職後の端末返却時の漏洩など、現実的なリスクが多数あります。代わりに次のいずれかを使います。

# 推奨1: apiKeyHelper にスクリプトを指定（~/.claude/settings.json）
# {
#   "apiKeyHelper": "/usr/local/bin/get-anthropic-key.sh"
# }

# 推奨2: macOS Keychain から取得
export ANTHROPIC_API_KEY="$(security find-generic-password -s anthropic-api -w)"

# 推奨3: 1Password CLI などのシークレットマネージャ経由
export ANTHROPIC_API_KEY="$(op read 'op://Private/Anthropic API/credential')"

API キーを誤って Git にコミットしてしまった場合は、まずConsoleでキーを直ちに失効させ、その後 git 履歴の改ざんを行います。失効を先に行わないと、履歴上のキーで第三者に課金される可能性があります。

複数インストール混在の検出

# macOS/Linux
which -a claude
ls -la ~/.local/bin/claude
ls -la ~/.claude/local/      # 旧npm local install
npm -g ls @anthropic-ai/claude-code 2>/dev/null

# Windows PowerShell
where.exe claude
Test-Path "$env:USERPROFILE\.local\bin\claude.exe"

旧 npm global / 旧 npm local / Homebrew / WinGet が同時に入っている場合は、ネイティブインストーラー版（~/.local/bin/claude または %USERPROFILE%\.local\bin\claude.exe）以外を削除します。

定期メンテナンス（週次/月次）

頻度	アクション	コマンド
毎セッション開始時	自己診断	/doctor
セッション中	コンテキストが大きくなったら圧縮	/compact
セッション中	使用量を確認	/cost / /usage
タスク切り替え時	Claude Code を再起動	ターミナル再起動
週次	Claude Code をアップデート	claude update
週次	認証状態を確認	/status
月次	CLAUDE.md の肥大化を確認	wc -c CLAUDE.md
月次	MCP ログを掃除	rm ~/Library/Logs/Claude/mcp-*.log
問題発生時	自己診断＋詳細ログ	/doctor → /heapdump → MCP ログ確認

ログ自動収集スクリプト例

問題報告時にすぐ提出できる「現状スナップショット」を作成するスクリプト例です。

#!/usr/bin/env bash
set -euo pipefail
OUT=~/Desktop/claude-code-diagnostics-$(date +%Y%m%d-%H%M%S)
mkdir -p "$OUT"

claude --version > "$OUT/version.txt" 2>&1 || true
claude doctor > "$OUT/doctor.txt" 2>&1 || true
env | grep -E '^(ANTHROPIC_|CLAUDE_|NODE_|HTTPS_PROXY|HTTP_PROXY|USE_BUILTIN_RIPGREP|MAX_THINKING_TOKENS)' > "$OUT/env.txt"
cp -r ~/Library/Logs/Claude "$OUT/mcp-logs" 2>/dev/null || true
cp ~/.claude/settings.json "$OUT/settings.json" 2>/dev/null || true

echo "Diagnostics saved to: $OUT"

組織のClaude Code 導入トラブルゼロ化支援

Claude Code を組織で導入する際、本記事で扱ったエラーの大半は 事前検証・設定代行・運用ガイドライン で予防できます。koromo は次のような領域で導入支援を提供しています。

• Anthropic Admin Console 設定代行: Routines / Claude Code 許可ポリシー / メンバーロールの整備
• 企業プロキシ・SSL証明書の事前検証: NODE_EXTRA_CA_CERTS の社内配布、ホワイトリスト交渉
• MCP統合のレビュー: 社内 MCP サーバーの設計レビュー、サブエージェントへの継承設計、認証情報の安全な管理
• 失敗事例の予防共有: 「API key が古いまま社員が入社」「Routines が全社で無効化されていた」「クロスFS遅延で開発体験が悪化」「Worker クラッシュで再起動ループ」などの典型例から、運用ガイドラインを設計

エンタープライズ規模での Claude Code 導入 も併せてご覧ください。

トラブルシューティングのベストプラクティス

日常的なメンテナンス習慣を身につけることで、エラー発生を予防し、発生時にも素早く対処できます。

エラー発生時の基本フロー

1. 逆引きインデックスでエラーメッセージを検索 — 本記事冒頭のテーブルから直接該当セクションへ
2. /doctor を実行 — インストール、設定、MCP、認証を一括診断
3. 公式リソースを参照 — status.claude.com でサービス障害を確認
4. ログを確認 — 前述の MCP デバッグログパスから直近のログをチェック
5. /feedback で報告 — 公式の対処法に該当しなければ Anthropic に直接フィードバック

公式サポートリソース

リソース	用途	アクセス方法
サービス稼働状況	障害発生時の確認	status.claude.com
エラーリファレンス	公式の全エラー一覧	code.claude.com/docs/en/errors
インストールトラブル	インストール全エラー	code.claude.com/docs/en/troubleshoot-install
フィードバック送信	バグ報告・機能要望	/feedback
既知の問題	同じ問題の確認・報告	GitHub Issues
公式ドキュメント	最新の仕様確認	code.claude.com/docs

よくある質問

まとめ

Claude Code のエラーは「インストール系」「実行時系」「環境依存系」の3カテゴリに分類でき、それぞれに体系的な解決アプローチがあります。最短経路は次の3ステップです。

1. 逆引きインデックス（50+項目） から該当エラーを探す
2. 見つからなければ /doctor を実行して切り分ける
3. それでも解決しない場合は /heapdump や MCP ログ で詳細を解析

2026年は Autocompact thrashing、Worker クラッシュ、セッション制限強化、USE_BUILTIN_RIPGREP=0、MAX_THINKING_TOKENS の挙動変更、Routines / Your organization has disabled Claude subscription / Extra inputs not permitted など、新しい挙動が次々に追加されています。ultrathink キーワードのような旧来の対処法は deprecated になっているものもあるため、本記事の最新情報を参照しながら対応してください。

本記事で紹介した対処法で解決しない場合は、status.claude.com で障害情報を確認し、/feedback コマンドで Anthropic に直接報告してください。

Claude Code の活用をさらに深めたい方は、Claude Code完全ガイド で基本的な使い方から応用テクニックまで体系的に学べます。エンタープライズ規模での導入や、AI 開発の効率化にお悩みの方は、koromo のAI開発支援サービスもご検討ください。