iii-engine installer failed. Fallbacks: Docker (`docker pull

Error message

iii-engine installer failed. Fallbacks: Docker (`docker pull iiidev/iii:${IIPINNED_VERSION}`) or download manually from https://github.com/iii-hq/iii/releases/tag/iii%2Fv${IIPINNED_VERSION}.

What it means

The composed shell command (curl the pinned iii release archive, extract with tar, place binary in ~/.agentmemory/bin) exited non-zero when run via runCommand with label "Installing iii-engine vX (pinned)". Because runCommand suppresses the script's raw output, the CLI prints this warning listing Docker and manual download fallbacks and reports ok:false with no binary path.

Source

Thrown at src/cli.ts:1414

      .filter(Boolean)
      .join(", ");
    p.log.warn(`${missing} not found. Cannot auto-install iii-engine.`);
    return { ok: false, binPath: null };
  }

  const binDir = agentmemoryBinDir();
  const binPath = privateIiiPath();
  const installCmd = [
    `mkdir -p "${binDir}"`,
    `curl -fsSL "${releaseUrl}" | tar -xz -C "${binDir}"`,
    `chmod +x "${binPath}"`,
  ].join(" && ");
  const installerOk = runCommand(shBin, ["-c", installCmd], {
    label: `Installing iii-engine v${IIPINNED_VERSION} (pinned)`,
    optional: true,
  });
  if (!installerOk) {
    p.log.warn(
      `iii-engine installer failed. Fallbacks: Docker (\`docker pull iiidev/iii:${IIPINNED_VERSION}\`) or download manually from https://github.com/iii-hq/iii/releases/tag/iii%2Fv${IIPINNED_VERSION}.`,
    );
    return { ok: false, binPath: null };
  }
  return { ok: true, binPath };
}

type StartupFailure = {
  kind: "no-engine" | "no-docker-compose" | "engine-crashed" | "docker-crashed";
  stderr?: string;
  binary?: string;
};

let startupFailure: StartupFailure | null = null;
let activeStartupStderr = createStartupStderrCapture();

function printCapturedStartupStderr(): void {
  const stderr = activeStartupStderr.text().trim();

View on GitHub (pinned to e04ba88819)

Solutions

Re-run the same steps manually to see the real error: curl the release URL and extract with tar yourself.
Use the Docker fallback: `docker pull iiidev/iii:<pinned-version>`.
Download the engine binary manually from https://github.com/iii-hq/iii/releases/tag/iii%2Fv<pinned> and place it at the private path (~/.agentmemory/bin).
Ensure ~/.agentmemory/bin exists and is writable; retry if it was a transient network failure.

Example fix

// before: blocked download
$ agentmemory start  # iii-engine installer failed
// after: manual fallback
$ mkdir -p ~/.agentmemory/bin && curl -L <release-url> | tar xz -C ~/.agentmemory/bin
$ agentmemory start

Defensive patterns

Strategy: retry

Validate before calling

// pre-flight: writable bin dir + reachable release host
try { mkdirSync("~/.agentmemory/bin", { recursive: true }); accessSync("~/.agentmemory/bin", constants.W_OK); }
catch { console.error("Cannot write to ~/.agentmemory/bin; fix permissions first."); }
const reachable = spawnSync("curl", ["-fsIL", iiiReleaseUrl()]).status === 0;
if (!reachable) console.error("Release host unreachable; check proxy/firewall.");

Try / catch

const { ok } = await runIiiInstaller();
if (!ok) {
  console.error("Installer failed; fallback to `docker pull iiidev/iii:<pinned>` or manual download, then retry.");
}

Prevention

Whitelist github.com release downloads in corporate networks.
Keep the home directory writable and with free disk space.
Retry once on transient failures before switching to Docker.
Pin and mirror the engine release internally for air-gapped environments.

When it happens

Trigger: runCommand(shBin, ["-c", installCmd]) fails: GitHub release download 404/blocked, network outage, no write permission on ~/.agentmemory/bin, tar extraction error, or checksum/asset mismatch for the pinned version.

Common situations: Corporate firewalls blocking github.com release downloads; read-only or quota-exceeded home directory; antivirus/EDR intercepting downloads; upstream removed or renamed the pinned release asset.

Related errors

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