{"record":{"id":"0beba98683ee33f4","repo":"coleam00/Archon","slug":"network-error-fetching-tarball-from-tarballurl","errorCode":null,"errorMessage":"Network error fetching tarball from ${tarballUrl}: ${toError(err).message}","messagePattern":"Network error fetching tarball from (.+?): (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/cli/src/commands/serve.ts","lineNumber":133,"sourceCode":"  // Phase markers, not metrics. When this stalls on windows CI the only surviving\n  // evidence is the log, and a single start line cannot say whether the wait sat\n  // in the fetch, the staged write, the spawn call, the child, or the rename\n  // afterwards (#2924). Each `web_dist.*` event below closes one phase and\n  // carries that phase's own durationMs, so the phases chain from here.\n  const downloadStartedAt = performance.now();\n  log.info({ version, targetDir }, 'web_dist.download_started');\n  console.log(`Web UI not found locally — downloading from release v${version}...`);\n\n  // Determine expected hash: prefer build-time embedded hash (independent trust anchor)\n  // over the remote checksums.txt (same-source, weaker guarantee).\n  let expectedHash: string;\n  let tarballRes: Response;\n  if (embeddedChecksum) {\n    expectedHash = parseEmbeddedChecksum(embeddedChecksum);\n    log.info({ source: 'embedded' }, 'web_dist.checksum_resolved');\n    console.log(`Downloading ${tarballUrl}...`);\n    tarballRes = await fetch(tarballUrl).catch((err: unknown) => {\n      throw new Error(`Network error fetching tarball from ${tarballUrl}: ${toError(err).message}`);\n    });\n  } else {\n    // Fallback: download checksums and tarball in parallel (dev mode or pre-build binaries)\n    console.log(`Downloading ${tarballUrl}...`);\n    const [checksumsRes, fetchedTarballRes] = await Promise.all([\n      fetch(checksumsUrl).catch((err: unknown) => {\n        throw new Error(\n          `Network error fetching checksums from ${checksumsUrl}: ${toError(err).message}`\n        );\n      }),\n      fetch(tarballUrl).catch((err: unknown) => {\n        throw new Error(\n          `Network error fetching tarball from ${tarballUrl}: ${toError(err).message}`\n        );\n      }),\n    ]);\n    if (!checksumsRes.ok) {\n      throw new Error(","sourceCodeStart":115,"sourceCodeEnd":151,"githubUrl":"https://github.com/coleam00/Archon/blob/0773b9745896ef0612e709c80845a0f7db315b19/packages/cli/src/commands/serve.ts#L115-L151","documentation":"downloadWebDist in the serve command wraps fetch(tarballUrl) failures into this error when an embedded checksum is present (release builds). Any network-level failure — DNS, TLS, connection refused, abort — while downloading the web UI tarball is translated with the original message preserved.","triggerScenarios":"serveCommand -> downloadWebDist with embeddedChecksum set; fetch() rejects because the host is unreachable, DNS fails, TLS fails, or the request is aborted.","commonSituations":"Offline or air-gapped server; corporate proxy/firewall blocking the download host; DNS misconfiguration; GitHub releases temporarily unreachable; missing HTTPS_PROXY env in containers.","solutions":["Check basic connectivity: curl -I <tarballUrl> from the same host to reproduce.","Configure proxy env vars (HTTPS_PROXY/HTTPS_PROXY for the fetch runtime) if behind a corporate proxy.","Retry after transient network issues; the download is idempotent.","Pre-seed the web dist locally or use a mirror by pointing the download URL at a reachable host."],"exampleFix":"// before: no proxy in container\narchon serve --download\n// after\nexport HTTPS_PROXY=http://proxy.corp:3128\narchon serve --download","handlingStrategy":"retry","validationCode":"// Pre-check reachability of the tarball URL\nconst head = await fetch(tarballUrl, { method: 'HEAD' }).catch(() => null);\nif (!head || !head.ok) throw new Error(`Tarball URL unreachable: ${tarballUrl}`);","typeGuard":null,"tryCatchPattern":"try {\n  await serveCommand({ downloadOnly: true });\n} catch (err) {\n  if (err instanceof Error && err.message.startsWith('Network error fetching tarball')) {\n    // check proxy/DNS, then retry with backoff\n  }\n}","preventionTips":["Configure HTTPS_PROXY/NO_PROXY correctly in containers.","Verify egress to the release host before automated deploys.","Add retry-with-backoff around serve --download in scripts."],"tags":["network","download","fetch","tarball"],"backgroundTag":"fetch-network-error","analyzedSha":"0773b9745896ef0612e709c80845a0f7db315b19","analyzedAt":"2026-09-01T02:28:07.064Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T05:18:18.240Z"}