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:

bash

# 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:

bash

ollama serve

Check endpoint in config:

yaml

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

Test connection:

bash

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:

bash

# 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:

bash

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

Verify files are being indexed:

bash

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

Try broader query:

bash

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):

bash

# Bad
grepai search "auth"

# Good
grepai search "user authentication middleware"

Configure boosting to penalize tests:

yaml

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

Check what's indexed:

bash

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:

bash

grepai watch --status

Restart daemon:

bash

grepai watch --stop
grepai watch --background

Force re-index:

bash

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:

bash

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:

yaml

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

Use faster model:

yaml

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

Use OpenAI for speed (if privacy allows):

yaml

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:

bash

ls -lh .grepai/index.gob

For large indices, use Qdrant:

yaml

store:
  backend: qdrant

Limit results:

bash

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:

yaml

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

Re-build symbol index:

bash

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:

bash

grepai mcp-serve

Check GrepAI is in PATH:

bash

which grepai

Verify MCP config:

bash

# 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:

yaml

embedder:
  model: nomic-embed-text  # Smaller

Use PostgreSQL or Qdrant instead of GOB
Reduce parallelism:

yaml

embedder:
  parallelism: 2

Issue: API key errors (OpenAI)

Symptom:

Error: 401 Unauthorized - Invalid API key

Solutions:

Check environment variable:

bash

echo $OPENAI_API_KEY

Ensure variable is exported:

bash

export OPENAI_API_KEY="sk-..."

Check key format in config:

yaml

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

Diagnostic Commands

Full System Check

bash

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

bash

# 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]

grepai-troubleshooting

NPX Install

Tags

SKILL.md Content

GrepAI Troubleshooting

When to Use This Skill

Quick Diagnostics

Common Issues

Issue: "Index not found"

Issue: "Cannot connect to embedding provider"

Issue: "Model not found"

Issue: Search returns no results

Issue: Search returns irrelevant results

Issue: Index is outdated

Issue: "Config not found"

Issue: Slow indexing

Issue: Slow searches

Issue: Trace not finding symbols

Issue: MCP not working

Issue: Out of memory

Issue: API key errors (OpenAI)

Diagnostic Commands

Full System Check

Reset Everything

Getting Help

Output Format