iii console install failed. Re-run manually: ${iiiConsoleI

Error message

iii console install failed. Re-run manually:
  ${iiiConsoleInstallHint()}

What it means

The CLI attempted to install the iii console by running III_CONSOLE_INSTALL_CMD through `sh -c` via runCommand (which hides the script's raw output and only reports success). If the script exits non-zero, this warning tells the user to re-run the install manually with the hint from iiiConsoleInstallHint, since the automated attempt produced no usable console installation.

Source

Thrown at src/cli.ts:1322

  if (p.isCancel(answer)) return state;
  if (answer === false) {
    writePrefs({ skipConsoleInstall: true });
    return state;
  }

  const shBin = whichBinary("sh");
  const curlBin = whichBinary("curl");
  if (!shBin || !curlBin) {
    p.log.warn(
      `curl or sh not found. Install manually:\n  ${iiiConsoleInstallHint()}`,
    );
    return state;
  }
  const ok = runCommand(shBin, ["-c", III_CONSOLE_INSTALL_CMD], {
    label: "Installing iii console",
  });
  if (!ok) {
    p.log.warn(
      `iii console install failed. Re-run manually:\n  ${iiiConsoleInstallHint()}`,
    );
    return state;
  }
  // Re-detect rather than trust install-script output paths.
  return detectIiiConsole();
}

function adoptRunningEngine(): void {
  try {
    const existingState = readEngineState();
    const existingPid = readEnginePidfile();
    if (existingState && existingPid) return;

    const pids = findEnginePidsByPort(getRestPort());
    const enginePid = pids[0];
    if (enginePid) {
      // A Docker-forwarded port is held by the VM/proxy process

View on GitHub (pinned to e04ba88819)

Solutions

Re-run the install script manually with the command from the hint to see full error output.
Check network/proxy access to the console release download URL (curl -I <url>).
Verify the install destination directory is writable.
Re-run `agentmemory` after a successful manual install — it re-detects the console via detectIiiConsole() rather than trusting script output.

Example fix

// before: silent automated failure
$ agentmemory start  # iii console install failed
// after: run manually to see the error
$ sh -c '<III_CONSOLE_INSTALL_CMD>'   # observe and fix underlying cause
$ agentmemory start

Defensive patterns

Strategy: retry

Validate before calling

// pre-flight: can we reach the console download host?
const probe = spawnSync("curl", ["-fsIL", consoleDownloadUrl], { encoding: "utf8" });
if (probe.status !== 0) console.error("Download host unreachable; fix network/proxy before install.");

Try / catch

const ok = runCommand(shBin, ["-c", III_CONSOLE_INSTALL_CMD]);
if (!ok) {
  console.error("Run the install script manually with the printed hint to see the real error, then retry.");
}

Prevention

Whitelist the console release download domain in corporate proxies.
Confirm OS/arch is supported by the install script.
Ensure the install destination is writable.
Retry after transient network failures; the CLI re-detects installed consoles automatically.

When it happens

Trigger: runCommand(shBin, ["-c", III_CONSOLE_INSTALL_CMD]) returns false: download fails (network/404), the install script detects an unsupported OS/arch, install destination is not writable, or the script itself errors.

Common situations: Corporate proxies blocking the console download URL; unsupported libc/arch (e.g. musl vs glibc mismatch); read-only install prefix; transient GitHub/network outages during install.

Related errors

AI-assisted analysis of rohitg00/agentmemory@e04ba88819 (2026-08-30). Data as JSON: /api/errors/32c55e88221666f5. Report an issue: GitHub.