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

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

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

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:

sgrep --threshold 0.3 "query" src/

Wrong Directory

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

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

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:

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

# 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).

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

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

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

Performance

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

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

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

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

Getting Help

.md
All docs →

Was this page helpful?