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:

- Check GrepAI documentation: [https://yoanbernabeu.github.io/grepai/](https://yoanbernabeu.github.io/grepai/)

- Search issues: [https://github.com/yoanbernabeu/grepai/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]

1. [Action item]