# Troubleshooting

Common issues and solutions when using sgrep.

## macOS Security Warning

If you manually downloaded the `sgrep` binary on macOS, you may see a security warning from Gatekeeper.

> **Note:** This only affects manual binary downloads. If you installed via `curl -fsSL https://sgrep.sh/install.sh | sh`, the installer handles this automatically.

### Quick Fix

```bash
# Remove quarantine flag and ad-hoc sign
xattr -d com.apple.quarantine $(which sgrep) 2>/dev/null
codesign -s - -f $(which sgrep)
```

### GUI Fix

1. Try running `sgrep --version` in your terminal (this triggers the security block)
2. Open **System Settings** → **Privacy & Security**
3. Scroll down and click **"Allow Anyway"** next to the sgrep warning
4. Run `sgrep --version` again and click **"Open Anyway"**

## Model Download Fails

On first run, sgrep downloads a 7.5MB model from sgrep.sh. If this fails:

```bash
# Check connectivity
curl -I https://sgrep.sh/model/embeddings.bin

# Force re-download
rm -rf ~/.cache/sgrep/models/potion-base-8M
sgrep "test" .
```

### Behind a Proxy

If you're behind a corporate proxy, set the standard environment variables:

```bash
export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080
sgrep "test" .
```

## No Results Found

If sgrep returns no results when you expect matches:

### Threshold Too High

The default threshold is 0.5. For exploratory searches, lower it:

```bash
sgrep --threshold 0.3 "query" src/
```

### Wrong Directory

sgrep searches the paths you specify. Make sure you're pointing at the right directory:

```bash
# Search current directory
sgrep "query" .

# Search specific directory
sgrep "query" src/
```

### Binary Files Skipped

sgrep only searches text files. Binary files, images, and compiled outputs are automatically skipped. Use `--verbose` to see what's being searched:

```bash
sgrep --verbose "query" .
```

## Hybrid Search Issues

### "No keyword matches found"

Hybrid mode combines semantic search with keyword matching. If you're searching for concepts rather than specific keywords, use regular (non-hybrid) mode:

```bash
# Semantic only (concepts)
sgrep "handle errors gracefully" src/

# Hybrid (when you know some keywords)
sgrep --hybrid "ConnectionPool timeout" src/
```

## Cache Issues

### Stale Results

If results seem outdated after editing files:

```bash
# Force re-embedding
sgrep --reindex "query" src/

# Or skip cache entirely
sgrep --no-cache "query" src/
```

### Cache Location

The cache is stored at `.sgrep/index.db` in your project directory. It's automatically ignored by git (`.sgrep/.gitignore` is created on first use).

```bash
# Check cache status
ls -la .sgrep/

# Clear cache
rm -rf .sgrep/
```

## Classification Issues

### Short Labels Not Matching

Short labels like "auth" may not match "authentication" in pure semantic mode. Use `--hybrid` for better matching with abbreviations:

```bash
# Pure semantic (may miss abbreviations)
sgrep -e "auth,db,config" src/

# Hybrid (catches abbreviations)
sgrep -e "auth,db,config" --hybrid src/
```

## Performance

### Slow First Search

The first search in a directory embeds all files. Subsequent searches use the cached embeddings and are near-instant.

```bash
# First search: ~1-2s (embedding)
sgrep "query" src/

# Second search: ~10ms (cached)
sgrep "different query" src/
```

### Large Codebases

For very large repos, you can limit the search scope:

```bash
# Search specific subdirectory
sgrep "query" src/core/

# Use --top-k to limit results
sgrep --top-k 5 "query" src/
```

## Getting Help

- **Docs:** [sgrep.sh/docs](/docs)
- **GitHub Issues:** [github.com/henrikalbihn/sgrep/issues](https://github.com/henrikalbihn/sgrep/issues)
- **Chat:** Use the chat assistant on any docs page (bottom-right bubble)