\nfix

Error message

${OFF_STATES.downloadUnreachable.line}\nfix: ${OFF_STATES.downloadUnreachable.fix}

What it means

setupInstallFailure is the catch-all failure path of the `caveman install` binary downloader. When the download error is not a 'stalled' BinaryDownloadError (e.g. network unreachable, DNS failure, HTTP error), it throws this generic 'download unreachable' message from OFF_STATES. It tells the user the binary could not be fetched from the release host.

Solutions

Check network connectivity to the release/download host (curl -I the download URL).
Configure proxy env vars (HTTPS_PROXY/HTTPS_PROXY) if behind a corporate proxy.
Retry the install command once connectivity is restored.
Manually download the binary and place it in binDir if the network cannot be fixed.

Example fix

// before
npx caveman install  // fails offline
// after
export HTTPS_PROXY=http://proxy.corp:8080
npx caveman install

Defensive patterns

Strategy: retry

Validate before calling

curl -fsSI "$DOWNLOAD_URL" >/dev/null && echo reachable || echo unreachable

Try / catch

try { await install() } catch (e) { if (String(e.message).includes('download unreachable')) { await waitForNetwork(); await install(); } else throw e; }

Prevention

Pre-check connectivity to the release host before installing.
Set HTTPS_PROXY correctly in CI/container environments.
Pin a fallback mirror or pre-download binaries for air-gapped setups.

When it happens

Trigger: Any non-timeout/non-stall failure inside the install download path: fetch of the release artifact throws (connection refused, DNS failure, TLS error, 404/403 HTTP response), and BinaryDownloadError.kind !== 'stalled'.

Common situations: Offline or firewalled environments blocking the release host; corporate proxies; wrong/removed release URL after a version change; DNS misconfiguration.

Related errors

AI-assisted analysis of JuliusBrussee/caveman@3ee70a1026 (2026-09-20). Data as JSON: /api/errors/022ccb691d69cd28. Report an issue: GitHub.

Appendix: source

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

  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 3ee70a1026)