grepai-troubleshooting

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

GrepAI Troubleshooting

GrepAI故障排除

This skill provides solutions for common GrepAI issues and diagnostic procedures.

此技能提供GrepAI常见问题的解决方案和诊断流程。

When to Use This Skill

何时使用此技能

GrepAI not working as expected
Search returning poor results
Index not updating
Connection or configuration errors

GrepAI未按预期工作
搜索返回的结果质量差
索引未更新
连接或配置错误

Quick Diagnostics

快速诊断

Run these commands to understand your setup:

bash

undefined

运行以下命令了解你的设置：

bash

undefined

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

undefined

cat .grepai/config.yaml

undefined

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

undefined

症状：

Error: Index not found. Run 'grepai watch' first.

原因： 此项目尚未创建索引。

解决方案：

bash

undefined

Initialize if needed

grepai init

Create the index

grepai watch

---

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

症状：

Error: Cannot connect to Ollama at http://localhost:11434

原因：

Ollama未运行
配置的端点错误
防火墙阻止了连接

解决方案：

启动Ollama：

bash

ollama serve

检查配置中的端点：

yaml

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

测试连接：

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

undefined

症状：

Error: Model 'nomic-embed-text' not found

原因： 嵌入模型尚未下载。

解决方案：

bash

undefined

Download the model

ollama pull nomic-embed-text

Verify

ollama list

---

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

症状： 搜索返回空结果或结果极少。

原因：

索引为空
文件被忽略
查询过于具体

解决方案：

检查索引状态：

bash

grepai status

Should show files > 0 and chunks > 0


2. Verify files are being indexed:
```bash


2. 验证文件是否被索引：
```bash

Check ignore patterns in config

cat .grepai/config.yaml | grep -A 20 "ignore:"


3. Try broader query:
```bash
grepai search "function"  # Very broad test

cat .grepai/config.yaml | grep -A 20 "ignore:"


3. 尝试更宽泛的查询：
```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

undefined

症状： 结果与你要查找的内容不匹配。

原因：

查询过于模糊
未配置权重调整
索引了错误的内容

解决方案：

优化查询（参考
```
grepai-search-tips
```
技能）：

bash

undefined

Bad

grepai search "auth"

Good

grepai search "user authentication middleware"


2. Configure boosting to penalize tests:
```yaml
search:
  boost:
    enabled: true
    penalties:
      - pattern: /tests/
        factor: 0.5

Check what's indexed:

bash

grepai status

grepai search "user authentication middleware"


2. 配置权重调整以降低测试文件的优先级：
```yaml
search:
  boost:
    enabled: true
    penalties:
      - pattern: /tests/
        factor: 0.5

检查索引内容：

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

症状： 最近的文件更改未出现在搜索结果中。

原因：

监听守护进程未运行
防抖延迟
文件不在索引支持的扩展名范围内

解决方案：

检查守护进程状态：

bash

grepai watch --status

重启守护进程：

bash

grepai watch --stop
grepai watch --background

强制重新索引：

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

症状：

Error: Config file not found at .grepai/config.yaml

原因： 此目录中未初始化GrepAI。

解决方案：

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

症状： 初始索引耗时极长。

原因：

代码库庞大
嵌入提供商速度慢
忽略规则不足

解决方案：

添加忽略规则：

yaml

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

使用更快的模型：

yaml

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

若隐私允许，使用OpenAI以提升速度：

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

症状： 搜索查询耗时数秒。

原因：

索引规模极大
大型代码库使用GOB存储
嵌入提供商速度慢

解决方案：

检查索引大小：

bash

ls -lh .grepai/index.gob

对于大型索引，使用Qdrant：

yaml

store:
  backend: qdrant

限制结果数量：

bash

grepai search "query" --limit 5

Issue: Trace not finding symbols

问题：Trace无法找到符号

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

症状：

grepai trace callers

无结果返回。

原因：

函数名称拼写错误
Trace未启用对应语言
符号索引已过时

解决方案：

检查精确的函数名称（区分大小写）
在配置中启用对应语言：

yaml

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

重新构建符号索引：

bash

rm .grepai/symbols.gob
grepai watch

Issue: MCP not working

问题：MCP无法工作

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

undefined

症状： AI助手无法使用GrepAI工具。

原因：

MCP配置错误
GrepAI不在PATH中
工作目录错误

解决方案：

手动测试MCP服务器：

bash

grepai mcp-serve

检查GrepAI是否在PATH中：

bash

which grepai

验证MCP配置：

bash

undefined

Claude Code

cat ~/.claude/mcp.json

Cursor

cat .cursor/mcp.json

---

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

症状： GrepAI崩溃或系统运行缓慢。

原因：

嵌入模型过大
GOB格式的索引规模极大
并行请求过多

解决方案：

使用更小的模型：

yaml

embedder:
  model: nomic-embed-text  # Smaller

使用PostgreSQL或Qdrant替代GOB
减少并行数：

yaml

embedder:
  parallelism: 2

Issue: API key errors (OpenAI)

问题：API密钥错误（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

症状：

Error: 401 Unauthorized - Invalid API key

解决方案：

检查环境变量：

bash

echo $OPENAI_API_KEY

确保变量已导出：

bash

export OPENAI_API_KEY="sk-..."

检查配置中的密钥格式：

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"

bash

#!/bin/bash
echo "=== GrepAI Diagnostics ==="

echo -e "\
1. Version:"
grepai version

echo -e "\
2. Status:"
grepai status

echo -e "\
3. Config:"
cat .grepai/config.yaml 2>/dev/null || echo "No config found"

echo -e "\
4. Index files:"
ls -la .grepai/ 2>/dev/null || echo "No .grepai directory"

echo -e "\
5. Ollama (if using):"
curl -s http://localhost:11434/api/tags | head -5 || echo "Ollama not responding"

echo -e "\
6. Daemon:"
grepai watch --status 2>/dev/null || echo "Daemon not running"

Reset Everything

完全重置

If all else fails, complete reset:

bash

undefined

如果所有方法都无效，执行完全重置：

bash

undefined

Remove all GrepAI data

rm -rf .grepai

Re-initialize

grepai init

Start fresh index

grepai watch

undefined

grepai watch

undefined

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

如果问题仍然存在：

查看GrepAI文档：https://yoanbernabeu.github.io/grepai/
搜索已有问题：https://github.com/yoanbernabeu/grepai/issues
创建新问题，包含以下信息：
- GrepAI版本（
```
grepai version
```
  ）
- 操作系统和架构
- 配置文件（移除敏感信息）
- 错误信息
- 复现步骤

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