Table of Contents
- Troubleshooting
Troubleshooting
Common issues and solutions.
Installation & Setup
'npx' is not recognized (Windows)
Use PowerShell instead of cmd:
npx ruflo@latest init wizard
Or use the install script in Git-Bash/WSL.
EACCES: permission denied (Linux/macOS)
npm cache clean --force
npx ruflo@latest init wizard
If still failing, check npm permissions:
npm list -g
If it shows permission errors, reset npm:
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH
Cannot find module '@anthropic-ai/sdk'
Install dependencies:
npx ruflo@latest doctor --fix
If still failing:
rm -rf node_modules package-lock.json
npm install
MCP Server Issues
MCP server failed to start
Check Node version:
node --version # Should be v20.x or higher
Register MCP server:
claude mcp add ruflo -- npx ruflo@latest mcp start
Verify registration:
claude mcp list
memory_store tool not available
Ensure MCP server is registered:
claude mcp add ruflo -- npx ruflo@latest mcp start
Then restart Claude Code.
MCP server crashes on startup
Check logs:
npx ruflo@latest daemon status --verbose
Clear cache and restart:
npm cache clean --force
npx ruflo@latest daemon stop
npx ruflo@latest daemon start
Memory & Storage
memory_search returns no results
Memory is empty. Store something first:
npx ruflo@latest memory store --key "test" --value "hello" --namespace patterns
npx ruflo@latest memory search --query "hello"
Out of memory with large corpus
Reduce HNSW cache size:
npx ruflo@latest config set memory.hnsw.cache-size 128
Or use RaBitQ quantization:
npx ruflo@latest embeddings init --quantization rabitq
Memory entries are missing
Check TTL (time-to-live):
npx ruflo@latest memory stats
If TTL has expired, they're automatically deleted. Store with no TTL:
npx ruflo@latest memory store --key "permanent" --value "data" --namespace patterns
# No --ttl flag = permanent storage
Swarm Coordination
Agent spawns but doesn't respond
Check swarm status:
npx ruflo@latest swarm status
npx ruflo@latest agent status <agent-id>
Restart the agent:
npx ruflo@latest agent stop <agent-id>
npx ruflo@latest agent spawn -t coder --name new-coder
Consensus timeout
Increase consensus timeout:
npx ruflo@latest config set consensus.timeout-ms 10000 # 10 seconds
Check network connectivity (for federation):
npx ruflo@latest federation status
SendMessage not delivered
Verify agent is in the swarm:
npx ruflo@latest hive-mind status
Check agent name matches exactly:
npx ruflo@latest agent list
Security & Verification
ruflo verify fails
Regenerate the manifest:
npm run build
npx ruflo@latest witness sign --manifest verification.md
For source-only checkouts (no build):
npx ruflo@latest verify --source-mode
AIDefence_scan blocked legitimate content
Adjust safety threshold:
npx ruflo@latest config set aidefence.pii-threshold 0.95
Lower threshold = stricter filtering.
API key not found
Set your Anthropic API key:
export ANTHROPIC_API_KEY=sk-ant-...
npx ruflo@latest doctor --fix
Or store in .env:
echo "ANTHROPIC_API_KEY=sk-ant-..." >> .env
npx ruflo@latest doctor --fix
Performance
Slow memory search
HNSW index is stale. Rebuild:
npx ruflo@latest memory migrate --force
Or profile the search:
npx ruflo@latest performance profile --target memory-search
High CPU usage
Check which worker is consuming resources:
npx ruflo@latest hooks worker status --verbose
Stop the problematic worker:
npx ruflo@latest hooks worker cancel <worker-id>
Agent timeouts
Increase task timeout:
npx ruflo@latest config set task.timeout-seconds 300 # 5 minutes
Cache Issues
cache_clean recipe (for #2127-style issues)
If you get version conflicts after updating:
npm cache clean --force
rm -rf ~/.ruflo/cache
rm -rf ~/.claude-flow/cache
npx ruflo@latest init wizard
This forces a fresh download and regenerates all local state.
Logs & Debugging
Enable verbose logging
npx ruflo@latest --log-level debug <command>
Or set environment variable:
CLAUDE_FLOW_LOG_LEVEL=debug npx ruflo@latest <command>
View daemon logs
npx ruflo@latest daemon logs --tail 100
Check system health
npx ruflo@latest doctor --fix
GitHub Issues
If you find a bug:
- Check existing issues: https://github.com/ruvnet/ruflo/issues
- Gather diagnostics:
npx ruflo@latest doctor --verbose > diagnostics.txt npx ruflo@latest swarm status > swarm-status.txt npx ruflo@latest memory stats > memory-stats.txt - Open a new issue with:
- Steps to reproduce
- Diagnostic output (above files)
- Ruflo version:
npx ruflo@latest --version - OS and Node version
Advanced: Nuclear Option
Reset everything (WARNING: data loss):
# Stop daemon
npx ruflo@latest daemon stop
# Remove all Ruflo state
rm -rf ~/.ruflo
rm -rf ~/.claude-flow
rm -rf ./.claude
rm -rf ./data/
# Reinstall
npx ruflo@latest init wizard
Ruflo v3.10.1 · GitHub Issues · Discussions
Getting Started
Reference
Architecture
Advanced
Operations
Ruflo v3.10.1 · npm · GitHub · Benchmarks