grepai-troubleshooting

仓库: yoanbernabeu/grepai-skills
安装量: 233
排名: #3750

安装

npx skills add https://github.com/yoanbernabeu/grepai-skills --skill grepai-troubleshooting

This skill provides solutions for common GrepAI issues and diagnostic procedures.

When to Use This Skill

  • GrepAI not working as expected

  • Search returning poor results

  • Index not updating

  • Connection or configuration errors

Quick Diagnostics

Run these commands to understand your setup:

# 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

Common Issues

Issue: "Index not found"

Symptom:

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

Cause: No index has been created for this project.

Solution:

# Initialize if needed
grepai init

# Create the index
grepai watch

Issue: "Cannot connect to embedding provider"

Symptom:

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

Causes:

  • Ollama not running

  • Wrong endpoint configured

  • Firewall blocking connection

Solutions:

  • Start Ollama:
ollama serve
  • Check endpoint in config:
embedder:
  endpoint: http://localhost:11434  # Verify this
  • Test connection:
curl http://localhost:11434/api/tags

Issue: "Model not found"

Symptom:

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

Cause: The embedding model hasn't been downloaded.

Solution:

# Download the model
ollama pull nomic-embed-text

# Verify
ollama list

Issue: Search returns no results

Symptom: Searches return empty or very few results.

Causes:

  • Index is empty

  • Files are being ignored

  • Query too specific

Solutions:

  • Check index status:
grepai status
# Should show files > 0 and chunks > 0
  • Verify files are being indexed:
# Check ignore patterns in config
cat .grepai/config.yaml | grep -A 20 "ignore:"
  • Try broader query:
grepai search "function"  # Very broad test

Issue: Search returns irrelevant results

Symptom: Results don't match what you're looking for.

Causes:

  • Query too vague

  • Boosting not configured

  • Wrong content indexed

Solutions:

  • Improve query (see grepai-search-tips skill):
# Bad
grepai search "auth"

# Good
grepai search "user authentication middleware"
  • Configure boosting to penalize tests:
search:
  boost:
    enabled: true
    penalties:
      - pattern: /tests/
        factor: 0.5
  • Check what's indexed:
grepai status

Issue: Index is outdated

Symptom: Recent file changes aren't appearing in search results.

Causes:

  • Watch daemon not running

  • Debounce delay

  • File not in indexed extensions

Solutions:

  • Check daemon status:
grepai watch --status
  • Restart daemon:
grepai watch --stop
grepai watch --background
  • Force re-index:
rm .grepai/index.gob
grepai watch

Issue: "Config not found"

Symptom:

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

Cause: GrepAI not initialized in this directory.

Solution:

grepai init

Issue: Slow indexing

Symptom: Initial indexing takes very long.

Causes:

  • Large codebase

  • Slow embedding provider

  • Not enough ignore patterns

Solutions:

  • Add ignore patterns:
ignore:
  - node_modules
  - vendor
  - dist
  - build
  - "*.min.js"
  • Use faster model:
embedder:
  model: nomic-embed-text  # Smaller, faster
  • Use OpenAI for speed (if privacy allows):
embedder:
  provider: openai
  model: text-embedding-3-small
  parallelism: 8

Issue: Slow searches

Symptom: Search queries take several seconds.

Causes:

  • Very large index

  • GOB storage on large codebase

  • Embedding provider slow

Solutions:

  • Check index size:
ls -lh .grepai/index.gob
  • For large indices, use Qdrant:
store:
  backend: qdrant
  • Limit results:
grepai search "query" --limit 5

Issue: Trace not finding symbols

Symptom: grepai trace callers returns no results.

Causes:

  • Function name spelled wrong

  • Language not enabled for trace

  • Symbols index out of date

Solutions:

  • Check exact function name (case-sensitive)

  • Enable language in config:

trace:
  enabled_languages:
    - .go
    - .js
    - .ts
  • Re-build symbol index:
rm .grepai/symbols.gob
grepai watch

Issue: MCP not working

Symptom: AI assistant can't use GrepAI tools.

Causes:

  • MCP config incorrect

  • GrepAI not in PATH

  • Working directory wrong

Solutions:

  • Test MCP server manually:
grepai mcp-serve
  • Check GrepAI is in PATH:
which grepai
  • Verify MCP config:
# Claude Code
cat ~/.claude/mcp.json

# Cursor
cat .cursor/mcp.json

Issue: Out of memory

Symptom: GrepAI crashes or system becomes slow.

Causes:

  • Large embedding model

  • Very large index in GOB format

  • Too many parallel requests

Solutions:

  • Use smaller model:
embedder:
  model: nomic-embed-text  # Smaller

  • Use PostgreSQL or Qdrant instead of GOB

  • Reduce parallelism:

embedder:
  parallelism: 2

Issue: API key errors (OpenAI)

Symptom:

Error: 401 Unauthorized - Invalid API key

Solutions:

  • Check environment variable:
echo $OPENAI_API_KEY
  • Ensure variable is exported:
export OPENAI_API_KEY="sk-..."
  • Check key format in config:
embedder:
  api_key: ${OPENAI_API_KEY}  # Uses env var

Diagnostic Commands

Full System Check

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

Reset Everything

If all else fails, complete reset:

# Remove all GrepAI data
rm -rf .grepai

# Re-initialize
grepai init

# Start fresh index
grepai watch

Getting Help

If issues persist:

GrepAI version (grepai version)

  • OS and architecture

  • Config file (remove secrets)

  • Error message

  • Steps to reproduce

Output Format

Diagnostic summary:

🔍 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]
← 返回排行榜