🔧 Troubleshooting

Common Issues

MCP server won't start

bash
# Check if port is in use
lsof -i :3000
# Kill existing process
kill -9 <PID>
# Restart MCP server
npx ruflo@latest mcp start

Agent spawn failures

bash
# Check available memory
free -m
# Reduce max agents if memory constrained
export CLAUDE_FLOW_MAX_AGENTS=5

Pattern search returning no results

bash
# Verify patterns are stored
npx ruflo@latest hooks metrics
# Re-run pretraining if empty
npx ruflo@latest hooks pretrain

Windows path issues

powershell
# Use forward slashes or escape backslashes
$env:CLAUDE_FLOW_MEMORY_PATH = "./data"
# Or use absolute path
$env:CLAUDE_FLOW_MEMORY_PATH = "C:/Users/name/ruflo/data"

Permission denied errors

bash
# Fix npm permissions (Linux/macOS)
sudo chown -R $(whoami) ~/.npm
# Or use nvm to manage Node.js

High memory usage

bash
# Enable garbage collection
node --expose-gc node_modules/.bin/ruflo
# Reduce HNSW parameters for lower memory
export CLAUDE_FLOW_HNSW_M=8
export CLAUDE_FLOW_HNSW_EF=100