JuliusBrussee/caveman · warning · Error

binary download unreachable — agents still launch; traffic i

Error message

binary download unreachable — agents still launch; traffic is NOT compressed or metered\nfix: caveman setup --install

What it means

Thrown by setupInstallFailure when fetching a Caveman release binary (or checksums.txt) from the GitHub release base fails with anything other than a 'stalled' BinaryDownloadError — i.e. DNS failure, connection refused, HTTP error, or missing response body. The CLI deliberately keeps going without the binaries: agents still launch, but traffic is not compressed or metered (byte-safe pass-through mode). The message itself points at the fix command.

Source

Thrown at packages/cli/src/index.ts:2156

  else console.error(line);
}

function installProgressComplete(
  name: string,
  platform: { os: string; arch: string },
  bytes: number,
) {
  const line = `${name}  ${platform.os}/${platform.arch}  ${(bytes / 1_000_000).toFixed(1)} MB  checksum verified`;
  if (interactive()) process.stderr.write(`\r${line}\n`);
  else console.error(line);
}

function setupInstallFailure(error: unknown, timeoutSeconds: number): never {
  if (interactive()) process.stderr.write("\n");
  if (error instanceof BinaryDownloadError && error.kind === "stalled") {
    throw new Error(`${OFF_STATES.downloadStalled(timeoutSeconds).line}\nfix: ${OFF_STATES.downloadStalled(timeoutSeconds).fix}`);
  }
  throw new Error(`${OFF_STATES.downloadUnreachable.line}\nfix: ${OFF_STATES.downloadUnreachable.fix}`);
}

function printInstallResult(
  installed: InstalledBinary[],
  platform: { os: string; arch: string },
  binDir: string,
  json: boolean,
  continuing = false,
) {
  if (json) {
    print({
      release: BINARY_RELEASE,
      platform: `${platform.os}/${platform.arch}`,
      target: binDir,
      binaries: installed,
      next: "caveman claude",
    });
    return;

View on GitHub (pinned to 27d5a3981a)

Solutions

1. Check network reachability of the release host (e.g. curl -I the release asset URL) and fix proxy/DNS/firewall settings
2. Re-run `caveman setup --install` once connectivity is restored
3. If in a restricted CI, pre-download the binaries and place them on PATH or in ~/.caveman/bin, or set CAVEMAN_PROXY_BIN/CAVEMAN_ENGINE_BIN etc. to the prebuilt binaries
4. Accept degraded mode if compression is not needed — agents still launch, traffic is uncompressed and unmetered

// Pre-flight reachability before triggering install:
import { spawnSync } from "node:child_process";
const reachable = spawnSync("curl", ["-Isf", "--max-time", "10", releaseAssetUrl]).status === 0;
if (!reachable) {
  console.error("release host unreachable — skipping caveman install, binaries must be pre-provisioned");
}

function isDownloadUnreachableError(e: unknown): boolean {
  return e instanceof Error && e.message.includes("binary download unreachable");
}

try {
  await runCavemanSetupInstall();
} catch (e) {
  if (isDownloadUnreachableError(e)) {
    // degraded mode is by design: agents still run uncompressed
    console.warn(e.message);
  } else throw e;
}

When it happens

Trigger: Running `caveman setup --install` (or setup continuing into install) with no network, behind a corporate proxy that blocks github release downloads, or when the release asset URL returns 404/5xx. Any fetchReleaseAsset rejection that is not a timeout surfaces here.

Common situations: Offline machine or sandboxed CI with no egress to github.com; HTTPS_PROXY/HTTPS_PROXY env vars intercepting TLS; firewall blocking large binary downloads; transient GitHub outage during first install.

Related errors

• cave_${harness}_upstream_version_unresolvable
• registration failed: HTTP ${response.status}
• cave_sandbox_os_network_isolation_unavailable
• caveman build: unresolved package dependency ${JSON.stringif
• signature check failed for checksums.txt — refusing to insta

AI-assisted analysis of JuliusBrussee/caveman@27d5a3981a (2026-08-15). Data as JSON: /api/errors/2937132dd65a0c14. Report an issue: GitHub.