grepai-troubleshooting

GrepAI のトラブルシューティング

このスキルでは、GrepAI のよくある問題への対処方法と診断手順を説明します。

このスキルを使用する場面

• GrepAI が期待どおりに動作しない場合
• 検索結果の精度が低い場合
• インデックスが更新されない場合
• 接続または設定のエラーが発生した場合

クイック診断

次のコマンドを実行して、現在の設定を確認します。

# Check GrepAI version
grepai version

# Check project status
grepai status

# Check Ollama (if using)
curl http://localhost:11434/api/tags

# Check config
cat .grepai/config.yaml

よくある問題

---

問題：「インデックスが見つかりません」

症状：

Error: Index not found. Run 'grepai watch' first.

原因： このプロジェクトのインデックスが作成されていません。

解決方法：

# Initialize if needed
grepai init

# Create the index
grepai watch

---

問題：「埋め込みプロバイダーに接続できません」

症状：

Error: Cannot connect to Ollama at http://localhost:11434

原因：

1. Ollama が起動していない
2. エンドポイントの設定が間違っている
3. ファイアウォールによって接続がブロックされている

解決方法：

1. Ollama を起動します。

ollama serve

2. 設定ファイルでエンドポイントを確認します。

embedder:
  endpoint: http://localhost:11434  # Verify this

3. 接続をテストします。

curl http://localhost:11434/api/tags

---

問題：「モデルが見つかりません」

症状：

Error: Model 'nomic-embed-text' not found

原因： 埋め込みモデルがダウンロードされていません。

解決方法：

# Download the model
ollama pull nomic-embed-text

# Verify
ollama list

---

問題：検索結果が表示されない

症状： 検索結果が空、または非常に少なくなります。

原因：

1. インデックスが空
2. ファイルが除外されている
3. クエリが具体的すぎる

解決方法：

1. インデックスの状態を確認します。

grepai status
# Should show files > 0 and chunks > 0

2. ファイルがインデックスに登録されていることを確認します。

# Check ignore patterns in config
cat .grepai/config.yaml | grep -A 20 "ignore:"

3. より広範なクエリを試します。

grepai search "function"  # Very broad test

---

問題：検索結果が無関係

症状： 検索結果が探している内容と一致しません。

原因：

1. クエリが曖昧すぎる
2. ブーストが設定されていない
3. インデックスに登録されたコンテンツが間違っている

解決方法：

1. クエリを改善します（grepai-search-tips スキルを参照）。

# Bad
grepai search "auth"

# Good
grepai search "user authentication middleware"

2. テストコードのスコアを下げるようにブーストを設定します。

search:
  boost:
    enabled: true
    penalties:
      - pattern: /tests/
        factor: 0.5

3. インデックスに登録されている内容を確認します。

grepai status

---

問題：インデックスが古い

症状： 最近のファイル変更が検索結果に反映されません。

原因：

1. 監視デーモンが実行されていない
2. デバウンスの遅延
3. ファイルの拡張子がインデックス対象に含まれていない

解決方法：

1. デーモンの状態を確認します。

grepai watch --status

2. デーモンを再起動します。

grepai watch --stop
grepai watch --background

3. インデックスを強制的に再構築します。

rm .grepai/index.gob
grepai watch

---

問題：「設定が見つかりません」

症状：

Error: Config file not found at .grepai/config.yaml

原因： このディレクトリで GrepAI が初期化されていません。

解決方法：

grepai init

---

問題：インデックス作成が遅い

症状： 初回のインデックス作成に非常に時間がかかります。

原因：

1. コードベースが大きい
2. 埋め込みプロバイダーが遅い
3. 除外パターンが不足している

解決方法：

1. 除外パターンを追加します。

ignore:
  - node_modules
  - vendor
  - dist
  - build
  - "*.min.js"

2. より高速なモデルを使用します。

embedder:
  model: nomic-embed-text  # Smaller, faster

3. プライバシー上問題がなければ、速度を優先して OpenAI を使用します。

embedder:
  provider: openai
  model: text-embedding-3-small
  parallelism: 8

---

問題：検索が遅い

症状： 検索クエリの処理に数秒かかります。

原因：

1. インデックスが非常に大きい
2. 大規模なコードベースで GOB ストレージを使用している
3. 埋め込みプロバイダーの処理が遅い

解決方法：

1. インデックスのサイズを確認します。

ls -lh .grepai/index.gob

2. インデックスが大きい場合は、Qdrant を使用します。

store:
  backend: qdrant

3. 結果数を制限します。

grepai search "query" --limit 5

---

問題：トレースでシンボルが見つからない

症状： grepai trace callers で結果が返されません。

原因：

1. 関数名のスペルが間違っている
2. トレースの対象言語が有効になっていない
3. シンボルインデックスが古い

解決方法：

1. 関数名が正確であることを確認します（大文字と小文字が区別されます）。

2. 設定で言語を有効にします。

trace:
  enabled_languages:
    - .go
    - .js
    - .ts

3. シンボルインデックスを再構築します。

rm .grepai/symbols.gob
grepai watch

---

問題：MCP が動作しない

症状： AI アシスタントが GrepAI のツールを使用できません。

原因：

1. MCP の設定が正しくない
2. GrepAI が PATH に含まれていない
3. 作業ディレクトリが間違っている

解決方法：

1. MCP サーバーを手動でテストします。

grepai mcp-serve

2. GrepAI が PATH に含まれていることを確認します。

which grepai

3. MCP の設定を確認します。

# Claude Code
cat ~/.claude/mcp.json

# Cursor
cat .cursor/mcp.json

---

問題：メモリ不足

症状： GrepAI がクラッシュする、またはシステムの動作が遅くなります。

原因：

1. 埋め込みモデルが大きい
2. GOB 形式のインデックスが非常に大きい
3. 並列リクエストが多すぎる

解決方法：

1. より小さなモデルを使用します。

embedder:
  model: nomic-embed-text  # Smaller

2. GOB の代わりに PostgreSQL または Qdrant を使用します。

3. 並列処理数を減らします。

embedder:
  parallelism: 2

---

問題：API キーのエラー（OpenAI）

症状：

Error: 401 Unauthorized - Invalid API key

解決方法：

1. 環境変数を確認します。

echo $OPENAI_API_KEY

2. 変数がエクスポートされていることを確認します。

export OPENAI_API_KEY="sk-..."

3. 設定ファイル内のキー形式を確認します。

embedder:
  api_key: ${OPENAI_API_KEY}  # Uses env var

---

診断コマンド

システム全体の確認

#!/bin/bash
echo "=== GrepAI Diagnostics ==="

echo -e "\n1. Version:"
grepai version

echo -e "\n2. Status:"
grepai status

echo -e "\n3. Config:"
cat .grepai/config.yaml 2>/dev/null || echo "No config found"

echo -e "\n4. Index files:"
ls -la .grepai/ 2>/dev/null || echo "No .grepai directory"

echo -e "\n5. Ollama (if using):"
curl -s http://localhost:11434/api/tags | head -5 || echo "Ollama not responding"

echo -e "\n6. Daemon:"
grepai watch --status 2>/dev/null || echo "Daemon not running"

すべてをリセット

それでも解決しない場合は、完全にリセットします。

# Remove all GrepAI data
rm -rf .grepai

# Re-initialize
grepai init

# Start fresh index
grepai watch

ヘルプの利用方法

問題が解決しない場合は、次の手順を実行してください。

1. GrepAI のドキュメントを確認します：https://yoanbernabeu.github.io/grepai/
2. イシューを検索します：https://github.com/yoanbernabeu/grepai/issues
3. 次の情報を添えて、新しいイシューを作成します。
   • GrepAI のバージョン（grepai version）
   • OS とアーキテクチャ
   • 設定ファイル（シークレットを削除してください）
   • エラーメッセージ
   • 再現手順

出力形式

診断の概要：

🔍 GrepAI Diagnostics

Version: 0.24.0
Project: /path/to/project

✅ Config: Found (.grepai/config.yaml)
✅ Index: 245 files, 1,234 chunks
✅ Embedder: Ollama (connected)
✅ Daemon: Running (PID 12345)
❌ Issue: [Description if any]

Recommended actions:
1. [Action item]
2. [Action item]