Network error fetching tarball from ${tarballUrl}: ${toError

Error message

Network error fetching tarball from ${tarballUrl}: ${toError(err).message}

What it means

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.

Source

Thrown at packages/cli/src/commands/serve.ts:133

  // Phase markers, not metrics. When this stalls on windows CI the only surviving
  // evidence is the log, and a single start line cannot say whether the wait sat
  // in the fetch, the staged write, the spawn call, the child, or the rename
  // afterwards (#2924). Each `web_dist.*` event below closes one phase and
  // carries that phase's own durationMs, so the phases chain from here.
  const downloadStartedAt = performance.now();
  log.info({ version, targetDir }, 'web_dist.download_started');
  console.log(`Web UI not found locally — downloading from release v${version}...`);

  // Determine expected hash: prefer build-time embedded hash (independent trust anchor)
  // over the remote checksums.txt (same-source, weaker guarantee).
  let expectedHash: string;
  let tarballRes: Response;
  if (embeddedChecksum) {
    expectedHash = parseEmbeddedChecksum(embeddedChecksum);
    log.info({ source: 'embedded' }, 'web_dist.checksum_resolved');
    console.log(`Downloading ${tarballUrl}...`);
    tarballRes = await fetch(tarballUrl).catch((err: unknown) => {
      throw new Error(`Network error fetching tarball from ${tarballUrl}: ${toError(err).message}`);
    });
  } else {
    // Fallback: download checksums and tarball in parallel (dev mode or pre-build binaries)
    console.log(`Downloading ${tarballUrl}...`);
    const [checksumsRes, fetchedTarballRes] = await Promise.all([
      fetch(checksumsUrl).catch((err: unknown) => {
        throw new Error(
          `Network error fetching checksums from ${checksumsUrl}: ${toError(err).message}`
        );
      }),
      fetch(tarballUrl).catch((err: unknown) => {
        throw new Error(
          `Network error fetching tarball from ${tarballUrl}: ${toError(err).message}`
        );
      }),
    ]);
    if (!checksumsRes.ok) {
      throw new Error(

View on GitHub (pinned to 0773b97458)

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.

Example fix

// before: no proxy in container
archon serve --download
// after
export HTTPS_PROXY=http://proxy.corp:3128
archon serve --download

Defensive patterns

Strategy: retry

Validate before calling

// Pre-check reachability of the tarball URL
const head = await fetch(tarballUrl, { method: 'HEAD' }).catch(() => null);
if (!head || !head.ok) throw new Error(`Tarball URL unreachable: ${tarballUrl}`);

Try / catch

try {
  await serveCommand({ downloadOnly: true });
} catch (err) {
  if (err instanceof Error && err.message.startsWith('Network error fetching tarball')) {
    // check proxy/DNS, then retry with backoff
  }
}

Prevention

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.

When it happens

Trigger: serveCommand -> downloadWebDist with embeddedChecksum set; fetch() rejects because the host is unreachable, DNS fails, TLS fails, or the request is aborted.

Common situations: Offline or air-gapped server; corporate proxy/firewall blocking the download host; DNS misconfiguration; GitHub releases temporarily unreachable; missing HTTPS_PROXY env in containers.

Related errors

AI-assisted analysis of coleam00/Archon@0773b97458 (2026-09-01). Data as JSON: /api/errors/0beba98683ee33f4. Report an issue: GitHub.