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:

1. Check existing issues: https://github.com/ruvnet/ruflo/issues
2. 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

3. 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