{"record":{"id":"2937132dd65a0c14","repo":"JuliusBrussee/caveman","slug":"binary-download-unreachable-agents-still-launch","errorCode":null,"errorMessage":"binary download unreachable — agents still launch; traffic is NOT compressed or metered\\nfix: caveman setup --install","messagePattern":"binary download unreachable — agents still launch; traffic is NOT compressed or metered\\\\nfix: caveman setup --install","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"warning","filePath":"packages/cli/src/index.ts","lineNumber":2156,"sourceCode":"  else console.error(line);\n}\n\nfunction installProgressComplete(\n  name: string,\n  platform: { os: string; arch: string },\n  bytes: number,\n) {\n  const line = `${name}  ${platform.os}/${platform.arch}  ${(bytes / 1_000_000).toFixed(1)} MB  checksum verified`;\n  if (interactive()) process.stderr.write(`\\r${line}\\n`);\n  else console.error(line);\n}\n\nfunction setupInstallFailure(error: unknown, timeoutSeconds: number): never {\n  if (interactive()) process.stderr.write(\"\\n\");\n  if (error instanceof BinaryDownloadError && error.kind === \"stalled\") {\n    throw new Error(`${OFF_STATES.downloadStalled(timeoutSeconds).line}\\nfix: ${OFF_STATES.downloadStalled(timeoutSeconds).fix}`);\n  }\n  throw new Error(`${OFF_STATES.downloadUnreachable.line}\\nfix: ${OFF_STATES.downloadUnreachable.fix}`);\n}\n\nfunction printInstallResult(\n  installed: InstalledBinary[],\n  platform: { os: string; arch: string },\n  binDir: string,\n  json: boolean,\n  continuing = false,\n) {\n  if (json) {\n    print({\n      release: BINARY_RELEASE,\n      platform: `${platform.os}/${platform.arch}`,\n      target: binDir,\n      binaries: installed,\n      next: \"caveman claude\",\n    });\n    return;","sourceCodeStart":2138,"sourceCodeEnd":2174,"githubUrl":"https://github.com/JuliusBrussee/caveman/blob/27d5a3981a347890211bb1bf2439e5c821a63bc9/packages/cli/src/index.ts#L2138-L2174","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Check network reachability of the release host (e.g. curl -I the release asset URL) and fix proxy/DNS/firewall settings","Re-run `caveman setup --install` once connectivity is restored","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","Accept degraded mode if compression is not needed — agents still launch, traffic is uncompressed and unmetered"],"exampleFix":null,"handlingStrategy":"retry","validationCode":"// Pre-flight reachability before triggering install:\nimport { spawnSync } from \"node:child_process\";\nconst reachable = spawnSync(\"curl\", [\"-Isf\", \"--max-time\", \"10\", releaseAssetUrl]).status === 0;\nif (!reachable) {\n  console.error(\"release host unreachable — skipping caveman install, binaries must be pre-provisioned\");\n}","typeGuard":"function isDownloadUnreachableError(e: unknown): boolean {\n  return e instanceof Error && e.message.includes(\"binary download unreachable\");\n}","tryCatchPattern":"try {\n  await runCavemanSetupInstall();\n} catch (e) {\n  if (isDownloadUnreachableError(e)) {\n    // degraded mode is by design: agents still run uncompressed\n    console.warn(e.message);\n  } else throw e;\n}","preventionTips":["Pre-install binaries via scripts/install-local-cli.sh or CAVEMAN_*_BIN env overrides in air-gapped CI","Whitelist the release download domain in corporate proxies","Treat the printed degraded-mode warning as expected in offline environments, not as a hard failure"],"tags":["network","install","download","degraded-mode"],"backgroundTag":null,"analyzedSha":"27d5a3981a347890211bb1bf2439e5c821a63bc9","analyzedAt":"2026-08-15T09:26:11.751Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}