grepai-troubleshooting

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

Common Issues

Issue: "Index not found"

Symptom:

Cause: No index has been created for this project.

Solution:

Issue: "Cannot connect to embedding provider"

Symptom:

Causes:

1. Ollama not running
2. Wrong endpoint configured
3. Firewall blocking connection

Solutions:

1. Start Ollama:

2. Check endpoint in config:

3. Test connection:

Issue: "Model not found"

Symptom:

Cause: The embedding model hasn't been downloaded.

Solution:

Issue: Search returns no results

Symptom: Searches return empty or very few results.

Causes:

1. Index is empty
2. Files are being ignored
3. Query too specific

Solutions:

1. Check index status:

2. Verify files are being indexed:

3. Try broader query:

Issue: Search returns irrelevant results

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

Causes:

1. Query too vague
2. Boosting not configured
3. Wrong content indexed

Solutions:

1. Improve query (see grepai-search-tips skill):

2. Configure boosting to penalize tests:

3. Check what's indexed:

Issue: Index is outdated

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

Causes:

1. Watch daemon not running
2. Debounce delay
3. File not in indexed extensions

Solutions:

1. Check daemon status:

2. Restart daemon:

3. Force re-index:

Issue: "Config not found"

Symptom:

Cause: GrepAI not initialized in this directory.

Solution:

Issue: Slow indexing

Symptom: Initial indexing takes very long.

Causes:

1. Large codebase
2. Slow embedding provider
3. Not enough ignore patterns

Solutions:

1. Add ignore patterns:

2. Use faster model:

3. Use OpenAI for speed (if privacy allows):

Issue: Slow searches

Symptom: Search queries take several seconds.

Causes:

1. Very large index
2. GOB storage on large codebase
3. Embedding provider slow

Solutions:

1. Check index size:

2. For large indices, use Qdrant:

3. Limit results:

Issue: Trace not finding symbols

Symptom: grepai trace callers returns no results.

Causes:

1. Function name spelled wrong
2. Language not enabled for trace
3. Symbols index out of date

Solutions:

1. Check exact function name (case-sensitive)

2. Enable language in config:

3. Re-build symbol index:

Issue: MCP not working

Symptom: AI assistant can't use GrepAI tools.

Causes:

1. MCP config incorrect
2. GrepAI not in PATH
3. Working directory wrong

Solutions:

1. Test MCP server manually:

2. Check GrepAI is in PATH:

3. Verify MCP config:

Issue: Out of memory

Symptom: GrepAI crashes or system becomes slow.

Causes:

1. Large embedding model
2. Very large index in GOB format
3. Too many parallel requests

Solutions:

1. Use smaller model:

2. Use PostgreSQL or Qdrant instead of GOB

3. Reduce parallelism:

Issue: API key errors (OpenAI)

Symptom:

Solutions:

1. Check environment variable:

2. Ensure variable is exported:

3. Check key format in config:

Diagnostic Commands

Full System Check

Reset Everything

If all else fails, complete reset:

Getting Help

If issues persist:

1. Check GrepAI documentation: https://yoanbernabeu.github.io/grepai/
2. Search issues: https://github.com/yoanbernabeu/grepai/issues
3. Create new issue with:
   • GrepAI version (grepai version)
   • OS and architecture
   • Config file (remove secrets)
   • Error message
   • Steps to reproduce

Output Format

Diagnostic summary: