grepai-troubleshooting

SKILL.md

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:**
```bash
# 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:

Check GrepAI documentation: https://yoanbernabeu.github.io/grepai/

Search issues: https://github.com/yoanbernabeu/grepai/issues

Create new issue with:

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]