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/

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