{"record":{"id":"4d0e66c9d993a490","repo":"rohitg00/agentmemory","slug":"iii-engine-binary-not-found-locally","errorCode":null,"errorMessage":"iii-engine binary not found locally.","messagePattern":"iii-engine binary not found locally\\.","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"src/cli.ts","lineNumber":1707,"sourceCode":"  // Wrong-version iii on PATH is a configuration trap: any prompt would\n  // confuse the user since they already \"have iii installed\". Skip the\n  // prompt and auto-install pinned engine to the private location.\n  const pathIiiMismatch = pathIii !== null && resolveCompatibleIii(pathIii) === null;\n\n  if (dockerOptIn && dockerBin && composeFile) {\n    choice = \"docker\";\n  } else if (pathIiiMismatch) {\n    choice = \"install\";\n    const detected = iiiBinVersion(pathIii!);\n    p.log.info(\n      `iii on PATH is v${detected ?? \"unknown\"} but agentmemory pins v${IIPINNED_VERSION}. ` +\n        `Installing pinned engine to ~/.agentmemory/bin (leaves your existing iii untouched).`,\n    );\n  } else if (!interactive) {\n    choice = \"install\";\n    p.log.info(\"Non-interactive environment detected — auto-installing iii-engine.\");\n  } else {\n    p.log.warn(`iii-engine binary not found locally.`);\n    const options: { value: Choice; label: string; hint?: string }[] = [\n      {\n        value: \"install\",\n        label: `Install iii v${IIPINNED_VERSION} to ~/.agentmemory/bin (~6MB, ~5s)`,\n        hint: \"recommended\",\n      },\n    ];\n    if (dockerBin && composeFile) {\n      options.push({ value: \"docker\", label: \"Use Docker compose\", hint: \"advanced\" });\n    }\n    options.push({ value: \"manual\", label: \"Show manual install steps and exit\" });\n\n    const picked = await p.select<Choice>({\n      message: \"How would you like to start iii-engine?\",\n      options,\n      initialValue: \"install\",\n    });\n    if (p.isCancel(picked)) {","sourceCodeStart":1689,"sourceCodeEnd":1725,"githubUrl":"https://github.com/rohitg00/agentmemory/blob/e04ba88819c365c9acf9d6661ea802143e728bd6/src/cli.ts#L1689-L1725","documentation":"When the CLI needs the pinned iii-engine but finds no local binary, it decides what to do based on interactivity: non-interactive environments auto-install silently, but in an interactive TTY it warns \"iii-engine binary not found locally.\" and presents a prompt offering to install the pinned version to ~/.agentmemory/bin (leaving any user-managed iii untouched). This is the warning printed just before that interactive prompt.","triggerScenarios":"Engine detection finds no iii-engine binary (neither on PATH nor at the private ~/.agentmemory/bin path) and the process is interactive — typically the first `agentmemory start` on a fresh machine, or after the private install was deleted.","commonSituations":"Fresh developer workstations; containers without the engine; users who cleared ~/.agentmemory; switching machines or profiles; CI environments that skipped the non-interactive auto-install flag.","solutions":["Answer the prompt with \"install\" (recommended) to install iii v<pinned> (~6MB, ~5s) to ~/.agentmemory/bin.","If you already manage iii yourself, choose the option to use your existing binary — though the hard-pinned version must match.","Pre-install manually: `npm install -g @agentmemory/agentmemory` setups or download from the iii GitHub releases and put it on PATH.","Re-run `agentmemory start`; after installation the warning disappears."],"exampleFix":"// before: fresh machine, no engine\n$ agentmemory start  # iii-engine binary not found locally.\n// after: accept recommended install\n? Choose: Install iii v<pinned> to ~/.agentmemory/bin (recommended)  ✔","handlingStrategy":"validation","validationCode":"import { existsSync } from \"node:fs\";\nimport { execFileSync } from \"node:child_process\";\nfunction engineAvailable(): boolean {\n  try { execFileSync(\"which\", [\"iii\"], { stdio: \"ignore\" }); return true; } catch {}\n  return existsSync(join(homedir(), \".agentmemory\", \"bin\"));\n}\nif (!engineAvailable()) console.warn(\"Run `agentmemory start` interactively once to install the engine.\");","typeGuard":null,"tryCatchPattern":"try {\n  await startEngine();\n} catch (e) {\n  if (String(e).includes(\"iii-engine\")) {\n    console.error(\"Engine missing; run `agentmemory start` in a TTY and choose install.\");\n  } else throw e;\n}","preventionTips":["Run `agentmemory start` once interactively on a new machine to install the pinned engine.","Avoid deleting ~/.agentmemory/bin when cleaning state.","In CI, rely on the non-interactive auto-install path or pre-install the engine in the image.","If you manage iii yourself, ensure its version matches the pin the CLI enforces."],"tags":["installation","iii-engine","interactive-prompt","first-run"],"backgroundTag":"engine-binary-not-found","analyzedSha":"e04ba88819c365c9acf9d6661ea802143e728bd6","analyzedAt":"2026-08-30T01:07:40.754Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}