iii-engine binary not available for ${platform()}/${process.

Error message

iii-engine binary not available for ${platform()}/${process.arch}. Use 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

runIiiInstaller downloads a pinned iii-engine binary from GitHub releases. It first computes releaseUrl/asset via iiiReleaseUrl/iiiReleaseAsset; if no release asset is published for the current platform/arch combination, releaseUrl is null and the CLI warns that no binary exists, suggesting Docker (iiidev/iii at the pinned version) or a manual download from the iii releases page.

Source

Thrown at src/cli.ts:1375

        configPath: findIiiConfig() || "",
        attached: true,
      });
    }
    if (enginePid && !existingPid) {
      p.log.info(c.ok(`Attached to existing iii-engine (pid ${enginePid})`));
    }
  } catch (err) {
    vlog(`adoptRunningEngine: ${err instanceof Error ? err.message : String(err)}`);
  }
}

async function runIiiInstaller(): Promise<{ ok: boolean; binPath: string | null }> {
  const releaseUrl = iiiReleaseUrl();
  const asset = iiiReleaseAsset();
  const isZipAsset = asset?.endsWith(".zip") === true;

  if (!releaseUrl) {
    p.log.warn(
      `iii-engine binary not available for ${platform()}/${process.arch}. Use 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 };
  }

  if (IS_WINDOWS || isZipAsset) {
    p.log.info(
      `Auto-install unavailable on ${platform()} — ${asset} isn't tar-compatible. Install manually:\n` +
        `  1. Download ${releaseUrl}\n` +
        `  2. Extract iii.exe and place it on PATH (e.g. %USERPROFILE%\\.local\\bin)\n` +
        `Or use Docker: docker pull iiidev/iii:${IIPINNED_VERSION}`,
    );
    return { ok: false, binPath: null };
  }

  const shBin = whichBinary("sh");
  const curlBin = whichBinary("curl");
  const tarBin = whichBinary("tar");

View on GitHub (pinned to e04ba88819)

Solutions

Use Docker as the message suggests: `docker pull iiidev/iii:<pinned-version>` and run the engine in a container.
Download a binary manually from https://github.com/iii-hq/iii/releases and place it where the CLI expects (private iii path under ~/.agentmemory/bin).
Build iii-engine from source and install it onto PATH so the CLI detects an existing binary instead of installing.
Check if a newer agentmemory/iii release added support for your platform and upgrade.

Example fix

// before: unsupported arch
$ uname -m  # armv7l — no release asset
// after: use Docker fallback
$ docker pull iiidev/iii:v<PINNED> && agentmemory start  # with docker engine mode

Defensive patterns

Strategy: fallback

Validate before calling

import { platform, arch } from "node:process";
// check upstream publishes an asset for this combo before relying on auto-install
const supported = ["darwin", "linux", "win32"].includes(platform()) &&
  ["x64", "arm64"].includes(arch());
if (!supported) console.error("No prebuilt iii-engine; plan Docker or source install.");

Try / catch

const { ok, binPath } = await runIiiInstaller();
if (!ok) {
  console.error("Falling back to Docker: docker pull iiidev/iii:<pinned>");
  await startEngineViaDocker();
}

Prevention

Verify your platform/arch has upstream release assets before adopting the tool.
Keep Docker available as a fallback on unusual architectures.
Track iii releases for new-platform support and upgrade.
Build iii from source onto PATH if you must run on unsupported combos.

When it happens

Trigger: Running agentmemory on a platform/arch with no published iii-engine release asset — e.g. linux/armv7, freebsd, or a new architecture added before iii published binaries — causing iiiReleaseUrl() to return null.

Common situations: Emerging hardware (new Apple Silicon or ARM SBCs) before upstream releases exist; niche OSes; running under emulated/QEMU architectures CI matrices that upstream doesn't publish assets for.

Related errors

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