{"record":{"id":"ea357c3629018150","repo":"ruvnet/ruflo","slug":"meta-proxy-is-not-installed-run-ruflo-proxy-inst","errorCode":null,"errorMessage":"meta-proxy is not installed. Run: ruflo proxy install","messagePattern":"meta-proxy is not installed\\. Run: ruflo proxy install","errorType":"exception","errorClass":"ProxyNotInstalledError","httpStatus":null,"severity":"error","filePath":"v3/@claude-flow/cli/src/proxy/lifecycle.ts","lineNumber":59,"sourceCode":"} from './paths.js';\n\nexport class ProxyNotInstalledError extends Error {\n  constructor() {\n    super('meta-proxy is not installed. Run: ruflo proxy install');\n    this.name = 'ProxyNotInstalledError';\n  }\n}\n\nexport class ProxyAlreadyRunningError extends Error {\n  constructor(public readonly pid: number) {\n    super(`meta-proxy is already running (pid ${pid}). Stop it first with: ruflo proxy stop`);\n    this.name = 'ProxyAlreadyRunningError';\n  }\n}\n\nfunction requireBinary(): string {\n  const bin = proxyBinaryPath();\n  if (!fs.existsSync(bin)) throw new ProxyNotInstalledError();\n  return bin;\n}\n\n/** Signal-0 liveness probe — cross-platform in Node, throws if the process is dead. */\nfunction isProcessRunning(pid: number): boolean {\n  try {\n    process.kill(pid, 0);\n    return true;\n  } catch {\n    return false;\n  }\n}\n\nexport interface ProxyStatus {\n  installed: boolean;\n  running: boolean;\n  pid: number | null;\n  stalePidFile: boolean;","sourceCodeStart":41,"sourceCodeEnd":77,"githubUrl":"https://github.com/ruvnet/ruflo/blob/fa13ee4ad60ac2090b1480656eb233521790d640/v3/@claude-flow/cli/src/proxy/lifecycle.ts#L41-L77","documentation":"Every proxy lifecycle operation (start, foreground, background, stop) first calls requireBinary(), which checks fs.existsSync(proxyBinaryPath()) and throws ProxyNotInstalledError when the meta-proxy binary is absent. The binary is not bundled with the CLI — it is downloaded, signature-verified, and placed only by `ruflo proxy install`.","triggerScenarios":"Running `ruflo proxy start` (or `proxy stop`, or any code path reaching requireBinary()) before `ruflo proxy install` has ever run on this machine; or after the binary file at proxyBinaryPath() was deleted or the state directory was cleaned.","commonSituations":"Fresh npm install of the CLI on a new machine; CI runners with ephemeral home directories where install state never persists; users assuming the proxy ships inside the CLI package; cleanup tools purging dot-state directories.","solutions":["Run `ruflo proxy install` to download, signature-verify, and place the binary","Confirm detection with `ruflo proxy status` before retrying the lifecycle command","If install itself fails, fix that error first (network, platform support) — start will keep throwing until the binary exists"],"exampleFix":"# before\nruflo proxy start   # ProxyNotInstalledError\n# after\nruflo proxy install && ruflo proxy start","handlingStrategy":"validation","validationCode":"import { existsSync } from 'node:fs';\nimport { execFileSync } from 'node:child_process';\n// Cheap pre-check via the CLI before starting\nconst installed = execFileSync('ruflo', ['proxy', 'status'], { encoding: 'utf8' });\n// Or, if importing the module: import { proxyBinaryPath } from '@claude-flow/cli/.../proxy/paths.js';\n// const installed = existsSync(proxyBinaryPath());","typeGuard":"const isProxyNotInstalled = (e: unknown): e is Error =>\n  e instanceof Error && e.name === 'ProxyNotInstalledError';","tryCatchPattern":"try {\n  await startForeground();\n} catch (e) {\n  if (isProxyNotInstalled(e)) {\n    execSync('ruflo proxy install');   // self-heal once\n    await startForeground();\n  } else throw e;\n}","preventionTips":["Make `ruflo proxy install` the first step of every setup script","Gate lifecycle commands behind a status check in automation","Treat a missing binary as a setup problem — install it, never fabricate or copy it manually"],"tags":["proxy","lifecycle","installation","missing-binary"],"backgroundTag":"binary-not-installed","analyzedSha":"fa13ee4ad60ac2090b1480656eb233521790d640","analyzedAt":"2026-08-18T21:34:22.708Z","contentChangedAt":"2026-08-18T21:34:22.708Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}