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

このスキルは一般的な GrepAI の問題と診断手順の解決策を提供します。

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

• GrepAI が想定通りに機能していない
• 検索結果の質が低い
• インデックスが更新されていない
• 接続またはコンフィグ関連のエラー

クイック診断

以下のコマンドを実行してセットアップを確認します：

# GrepAI のバージョンを確認
grepai version

# プロジェクトの状態を確認
grepai status

# Ollama を確認（使用している場合）
curl http://localhost:11434/api/tags

# コンフィグを確認
cat .grepai/config.yaml

よくある問題

---

問題: 「Index not found」

症状：

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

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

解決方法：

# 必要に応じて初期化
grepai init

# インデックスを作成
grepai watch

---

問題: 「Cannot connect to embedding provider」

症状：

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

原因：

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

解決方法：

1. Ollama を起動します：

ollama serve

2. コンフィグのエンドポイントを確認します：

embedder:
  endpoint: http://localhost:11434  # これを確認

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

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

---

問題: 「Model not found」

症状：

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

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

解決方法：

# モデルをダウンロード
ollama pull nomic-embed-text

# 確認
ollama list

---

問題: 検索が結果を返さない

症状： 検索が空の結果または非常に少ない結果を返します。

原因：

1. インデックスが空である
2. ファイルが無視されている
3. クエリが特定的すぎる

解決方法：

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

grepai status
# ファイル数 > 0 およびチャンク数 > 0 を表示すべき

2. ファイルがインデックス対象であることを確認します：

# コンフィグの無視パターンを確認
cat .grepai/config.yaml | grep -A 20 "ignore:"

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

grepai search "function"  # 非常に広いテスト

---

問題: 検索が無関係な結果を返す

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

原因：

1. クエリが曖昧である
2. ブースティングが設定されていない
3. 間違ったコンテンツがインデックスされている

解決方法：

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

# 悪い例
grepai search "auth"

# 良い例
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

---

問題: 「Config not found」

症状：

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  # より小さく、高速

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

---

問題: Trace がシンボルを見つけられない

症状： 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  # より小さい

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}  # 環境変数を使用

---

診断コマンド

完全なシステムチェック

#!/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"

すべてをリセット

すべてが失敗した場合は、完全にリセットします：

# すべての GrepAI データを削除
rm -rf .grepai

# 再初期化
grepai init

# 新しいインデックスを開始
grepai watch

ヘルプを取得

問題が解決しない場合：

1. GrepAI ドキュメントを確認します：https://yoanbernabeu.github.io/grepai/
2. issue を検索します：https://github.com/yoanbernabeu/grepai/issues
3. 以下の情報とともに新しい issue を作成します：
   • 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]