トラブルシューティングガイド
NexusCore開発・運用時の既知の問題と解決策。
MCP接続
protocolVersion 不一致
症状: MCPサーバーが接続に失敗する。ログに Server's protocol version is not supported が表示される。
原因: MCPサーバーの protocolVersion とクライアント（Claude Code CLI / Desktop）の対応バージョンが異なる。
対応:
- Claude Code Desktop (v1.6608時点):
"2024-11-05"のみ対応 - Claude Code CLI (WSL2): 新バージョンも対応
- 両環境で動作させる場合は
"2024-11-05"に統一
// MCPサーバー設定
{
"protocolVersion": "2024-11-05" // ← Desktop互換
}
確認手順:
- Desktop:
%APPDATA%\Claude\logs\main.logを確認 - CLI: 標準エラー出力を確認
WSL2環境での $HOME 解決問題
症状: MCPサーバー起動スクリプトで環境変数が読み込めない。
原因: WSL2の $HOME が /c/Users/ユーザー名 に解決され、~/.secrets.env のパスがずれる。
対応: 起動スクリプトで絶対パスを使用:
# NG
source ~/.secrets.env
# OK
source /home/yn4416/.secrets.env
LLMプロバイダー
429 レート制限
症状: プロバイダーから429エラーが返却される。
自動対応: Phase 1のフォールバック機構が自動で次候補モデルに切り替え。
手動確認:
# ログで429発生状況を確認
grep "rate-limited" logs/llm_calls.jsonl | tail -20
環境変数:
NEXUS_MAX_FALLBACKS: フォールバック最大試行数（デフォルト3）NEXUS_429_COOLDOWN_SEC: 429後のクールダウン秒（デフォルト60）
スタブモードからの復帰
症状: 全呼び出しがスタブ応答になる。
原因: APIキー未設定 または NEXUS_DRY_RUN=1。
確認:
# キー健全性チェックのログを確認
grep "KeyHealth" logs/*.log
# モード確認
grep '"mode"' logs/llm_calls.jsonl | tail -5
テスト
テストがモック汚染で失敗する
症状: テストファイルを個別には通るが、全体実行で失敗する。
原因: sys.modules への MagicMock 注入が後続テストを汚染。
対応: conftest.py の sys.modules 隔離機構が自動で対処。独自のモックを注入する場合は @pytest.fixture(autouse=True) で確実にクリーンアップすること。
外部APIのテスト
方針: 外部パッケージ依存テストはモック必須。CI-safeに保つこと。
環境構築
.env が読み込まれない
確認:
# 複数候補から自動検索
# 1. NEXUSCORE_ENV_FILE 環境変数
# 2. プロジェクトルート/.env
# 3. src/.env
# 4. src/nexuscore/.env
Pythonバージョン
NexusCoreは Python 3.11+ を要求。python コマンドが見つからない場合は python3 を使用。