Troubleshooting

Quick solutions for common issues. For detailed troubleshooting, see the full guide on GitHub .

Installation Issues

dev: command not found

Global npm bin directory not in PATH:

# Find npm bin directory
npm config get prefix
 
# Add to shell profile (~/.zshrc or ~/.bashrc)
export PATH="$(npm config get prefix)/bin:$PATH"
 
# Reload
source ~/.zshrc

Permission errors on install

# Option 1: Use npx (no install needed)
npx dev-agent index .
 
# Option 2: Fix npm permissions
npm config set prefix ~/.npm-global
export PATH=~/.npm-global/bin:$PATH
npm install -g dev-agent

Indexing Issues

”No source files found"

# Verify you're in repository root
ls -la  # Should see .git/
 
# Check for supported files
find . -name "*.ts" -o -name "*.js" | head -10

"Vector storage initialization failed”

# Check permissions
ls -la ~/.dev-agent/
 
# Clear and rebuild
rm -rf ~/.dev-agent/indexes/*
dev index

Antfly container crashes (exit code 137)

The container is running out of memory. Docker Desktop defaults to 2GB which is not enough for embedding models.

Fix: Increase Docker memory to 8GB+ in Docker Desktop → Settings → Resources → Memory, then:

dev reset
dev setup

MCP Server Issues

Server won’t start

# 1. Check if indexed
ls -la ~/.dev-agent/indexes/
 
# 2. Verify installation
dev mcp list --cursor  # or without --cursor
 
# 3. Test manually
dev mcp start --verbose

”Repository not indexed” in Cursor

# Index the workspace
dev index
 
# Restart Cursor

Rate limit errors (429)

• Wait for retryAfterMs period
• Check health: dev_status section="health"
• Restart AI tool if persistent

Search Issues

No results

# Verify indexed
dev stats
 
# Re-index if needed
dev index

Tips for better searches:

• Use natural language, not exact code
• Describe what code does
• Try different phrasings

Poor relevance

Adjust score threshold:

• 0.7+ — Precise matches only
• 0.4-0.6 — Balanced
• 0.25-0.3 — Exploratory

Antfly Issues

”Embedding model is missing” after dev setup

If dev setup says “Embedding model ready” but dev index fails with “model not found”, you may have a stale Docker container from a previous installation. The native binary and Docker container use separate model directories.

# Check if a Docker container is running
docker ps --filter name=dev-agent-antfly
 
# If so, remove it and switch to native
docker stop dev-agent-antfly && docker rm dev-agent-antfly
dev setup

Antfly server not running

If you see Failed to initialize Antfly store or fetch failed:

# Run setup (starts the server via Docker or native)
dev setup
 
# Or start manually
antfly swarm

Port conflict on startup

Antfly uses port 18080 (Docker) or 8080 (native). If another service is using that port:

# Check what's using the port
lsof -i :18080
 
# Use a custom port via environment variable
ANTFLY_URL=http://localhost:19090/api/v1 dev index

Old LanceDB data

If you’re upgrading from a previous version that used LanceDB:

# Old indexes are not compatible — re-index with Antfly
dev index --force
 
# Optionally clean up old LanceDB data
rm -rf ~/.dev-agent/indexes/*/vectors*

Quick Fixes

Clear everything and start fresh

dev setup              # Ensure Antfly is running
dev index --force    # Re-index from scratch
dev mcp install --cursor

Check health

Use dev_status with section="health" in Cursor/Claude Code

Enable debug logging

Cursor: Edit ~/.cursor/mcp.json:

"env": { "LOG_LEVEL": "debug" }

Getting Help

1. Run dev_status section="health" for diagnostics
2. Check full troubleshooting guide 
3. File an issue  with:
   • dev --version
   • dev_status section="health" output
   • Steps to reproduce