# How to Troubleshoot Ruflo Installation Problems: Complete Diagnostic Guide

> Troubleshoot Ruflo installation problems with our diagnostic guide. Run nx @claude-flow/cli@latest doctor to fix Node.js conflicts, missing API keys, and MCP server errors.

- Repository: [rUv/ruflo](https://github.com/ruvnet/ruflo)
- Tags: how-to-guide
- Published: 2026-03-09

---

**Run `npx @claude-flow/cli@latest doctor` to automatically diagnose and fix Ruflo installation issues, including Node.js version conflicts, missing API keys, and MCP server misconfigurations.**

When installing Ruflo from the `ruvnet/ruflo` repository, environment mismatches or permission errors can prevent the CLI from functioning correctly. This guide walks you through how to troubleshoot Ruflo installation problems using the built-in diagnostic tools and manual verification steps derived directly from the source code in `v3/@claude-flow/cli/src/commands/doctor.ts`.

## Run the Built-in Health Check with the Doctor Command

The fastest way to identify installation issues is to run the diagnostic suite implemented in [`doctor.ts`](https://github.com/ruvnet/ruflo/blob/main/doctor.ts). This command evaluates 15 distinct environment checks and provides automated fix suggestions.

```bash

# Full diagnostic check

npx @claude-flow/cli@latest doctor

# Show suggested fix commands

npx @claude-flow/cli@latest doctor --fix

```

### What the Doctor Command Checks

According to the source code in `v3/@claude-flow/cli/src/commands/doctor.ts`, the diagnostic tool validates the following components:

- **Node.js version** (≥ 20) – Checks `process.version` at lines 41-48
- **npm version** (≥ 9) – Executes `npm --version` at lines 58-66
- **Claude Code CLI** – Verifies `claude --version` at lines 55-63
- **Git** – Checks `git --version` at lines 58-61
- **Config file** – Validates JSON at [`.claude-flow/config.json`](https://github.com/ruvnet/ruflo/blob/main/.claude-flow/config.json) at lines 71-89
- **Daemon PID** – Detects running processes or stale PID files at lines 95-107
- **Memory DB** – Checks existence and size of `.claude-flow/memory.db` at lines 113-133
- **API keys** – Verifies `ANTHROPIC_API_KEY` or `CLAUDE_API_KEY` at lines 136-152
- **MCP servers** – Validates `claude-flow` entry in MCP config at lines 176-200
- **Disk space** – Checks free space via `df -Ph` at lines 206-226
- **TypeScript** – Runs `npx tsc --version` at lines 232-242
- **Platform permissions** – Checks executable bits and PowerShell policies at lines 250-267

If any check returns **fail** or **warn**, the doctor outputs a one-line fix command (e.g., `nvm install 20 && nvm use 20` for Node version issues).

## Fix Common Platform-Specific Installation Issues

### Linux (Ubuntu/Debian)

If `npm` is missing or outdated, install Node.js 20+ via Node Version Manager rather than the system package manager to avoid permission conflicts:

```bash

# Install nvm if missing

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# Install and use Node 20

nvm install 20 && nvm use 20

# Verify

node --version  # Should print v20.x.x

```

### macOS

Missing Git or Homebrew dependencies are common on fresh macOS installations. Install Homebrew first, then the required tools:

```bash

# Install Homebrew

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install dependencies

brew install git node

# Verify Ruflo doctor passes

npx @claude-flow/cli@latest doctor

```

### Windows PowerShell and Git Bash

Windows users often encounter execution policy restrictions or permission errors when running helper scripts.

**PowerShell Execution Policy:**

```powershell

# Check current policy

Get-ExecutionPolicy

# Set to RemoteSigned for current user

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

```

**Git Bash Permission Fixes:**

If you encounter `chmod`-style errors in Git Bash, manually set executable permissions:

```bash
chmod +x .claude/helpers/*.sh .claude/helpers/templates/*.sh

```

Alternatively, right-click the script files in Explorer, select Properties, and click **Unblock** if present.

## Validate the Helper System and Permissions

Ruflo ships with a helper layer used by Claude Code. Validate these scripts are executable and correctly configured:

```bash

# Linux/macOS validation

./.claude/helpers/claude-flow-v3.sh validate

# Expected output: "All checks passed!"

```

If validation fails, check the helper documentation in [`v3/helpers/docs/installation.md`](https://github.com/ruvnet/ruflo/blob/main/v3/helpers/docs/installation.md) for platform-specific setup instructions.

## Reinstall Critical Dependencies

### Claude Code CLI

If the doctor reports the Claude Code CLI is missing, force a clean reinstall:

```bash

# Remove old copy

npm uninstall -g @anthropic-ai/claude-code

# Fresh install

npm install -g @anthropic-ai/claude-code

# Verify

claude --version

```

### MCP Server Registration

If Ruflo-specific tools are invisible in Claude Desktop, verify the MCP server registration:

```bash

# List registered servers

claude mcp list

# Should show: claude-flow

```

If absent, add it manually:

```bash
claude mcp add claude-flow -- npx -y @claude-flow/cli@latest mcp start

```

For VS Code, add the same configuration to [`.vscode/mcp.json`](https://github.com/ruvnet/ruflo/blob/main/.vscode/mcp.json).

### Memory Database Initialization

A corrupted SQLite database can cause silent failures. If the doctor warns about the memory DB, reinitialize it:

```bash

# Remove corrupted database

rm .claude-flow/memory.db

# Reinitialize with force flag

npx @claude-flow/cli@latest memory init --force

```

## Key Source Files for Deep Troubleshooting

When manual intervention is required, inspect these specific files in the `ruvnet/ruflo` repository:

| File | Purpose | Location |
|------|---------|----------|
| [`doctor.ts`](https://github.com/ruvnet/ruflo/blob/main/doctor.ts) | Implements all 15 diagnostic checks and fix suggestions | `v3/@claude-flow/cli/src/commands/doctor.ts` |
| [`installation.md`](https://github.com/ruvnet/ruflo/blob/main/installation.md) | Platform-specific helper setup and permission fixes | [`v3/helpers/docs/installation.md`](https://github.com/ruvnet/ruflo/blob/main/v3/helpers/docs/installation.md) |
| [`CLAUDE.md`](https://github.com/ruvnet/ruflo/blob/main/CLAUDE.md) | CLI-to-Claude Code coordination and troubleshooting reference | `v3/@claude-flow/cli/CLAUDE.md` |
| [`claude-flow-v3.sh`](https://github.com/ruvnet/ruflo/blob/main/claude-flow-v3.sh) | Helper script wrapper for validation and status checks | [`.claude/helpers/claude-flow-v3.sh`](https://github.com/ruvnet/ruflo/blob/main/.claude/helpers/claude-flow-v3.sh) |

## Summary

To effectively troubleshoot Ruflo installation problems:

- **Start with the doctor**: Run `npx @claude-flow/cli@latest doctor` to identify specific failures across 15 environment checks.
- **Fix platform permissions**: Use `nvm` for Node version issues on Linux/macOS, `Set-ExecutionPolicy` for PowerShell on Windows, and `chmod` for helper scripts.
- **Verify critical components**: Ensure the Claude Code CLI is installed, the MCP server is registered, and the SQLite memory database is initialized.
- **Consult source files**: Reference [`doctor.ts`](https://github.com/ruvnet/ruflo/blob/main/doctor.ts) and [`installation.md`](https://github.com/ruvnet/ruflo/blob/main/installation.md) in the `ruvnet/ruflo` repository for implementation details when automated fixes fail.

## Frequently Asked Questions

### Why does the Ruflo doctor command report Node.js version errors?

The doctor command checks for Node.js version 20 or higher by reading `process.version` in `v3/@claude-flow/cli/src/commands/doctor.ts`. If your system Node is older, install version 20+ via `nvm install 20 && nvm use 20` or download it directly from nodejs.org.

### How do I fix PowerShell execution policy errors when installing Ruflo?

Windows PowerShell defaults to the `Restricted` policy, which prevents script execution. Run `Set-ExecutionPolicy -Scope CurrentUser RemoteSigned` to allow locally created scripts to run while requiring remote scripts to be signed. This is documented in [`v3/helpers/docs/installation.md`](https://github.com/ruvnet/ruflo/blob/main/v3/helpers/docs/installation.md).

### What should I do if Ruflo tools don't appear in Claude Desktop?

This indicates the MCP server is not registered. Run `claude mcp list` to verify; if `claude-flow` is missing, add it with `claude mcp add claude-flow -- npx -y @claude-flow/cli@latest mcp start`. For VS Code, add the same configuration to [`.vscode/mcp.json`](https://github.com/ruvnet/ruflo/blob/main/.vscode/mcp.json).

### How do I repair a corrupted Ruflo memory database?

If the doctor reports warnings about `.claude-flow/memory.db`, delete the corrupted file with `rm .claude-flow/memory.db` and reinitialize using `npx @claude-flow/cli@latest memory init --force`. This recreates the hybrid SQLite + HNSW vector store required for Ruflo's context management.