Failed to download web UI: ${tarballRes.status} ${tarballRes

Error message

Failed to download web UI: ${tarballRes.status} ${tarballRes.statusText}

What it means

downloadWebDist fetches the archon-web.tar.gz release asset from a remote source and throws this when the HTTP response is not ok (tarballRes.ok is false). It surfaces the HTTP status code and status text so the operator can see whether the download endpoint rejected the request. It is an intentional fail-fast: serving a missing or corrupt web UI bundle is worse than refusing to start.

Source

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

      fetch(tarballUrl).catch((err: unknown) => {
        throw new Error(
          `Network error fetching tarball from ${tarballUrl}: ${toError(err).message}`
        );
      }),
    ]);
    if (!checksumsRes.ok) {
      throw new Error(
        `Failed to download checksums: ${checksumsRes.status} ${checksumsRes.statusText}`
      );
    }
    const checksumsText = await checksumsRes.text();
    expectedHash = parseChecksum(checksumsText, 'archon-web.tar.gz');
    log.info({ source: 'remote' }, 'web_dist.checksum_resolved');
    tarballRes = fetchedTarballRes;
  }

  if (!tarballRes.ok) {
    throw new Error(`Failed to download web UI: ${tarballRes.status} ${tarballRes.statusText}`);
  }
  const tarballBuffer = await tarballRes.arrayBuffer();

  // Verify checksum
  const hasher = new Bun.CryptoHasher('sha256');
  hasher.update(new Uint8Array(tarballBuffer));
  const actualHash = hasher.digest('hex');

  if (actualHash !== expectedHash) {
    throw new Error(`Checksum mismatch: expected ${expectedHash}, got ${actualHash}`);
  }
  console.log('Checksum verified.');
  const verifiedAt = performance.now();
  log.info({ durationMs: Math.round(verifiedAt - downloadStartedAt) }, 'web_dist.tarball_verified');

  // Extract to temp dir, then atomic rename
  const tmpDir = `${targetDir}.tmp`;
  const tarballPath = `${tmpDir}.tar.gz`;

View on GitHub (pinned to 0773b97458)

Solutions

Read the status in the message: retry after fixing the cause — 404 means the release asset is missing, so install/upgrade to a version whose release includes archon-web.tar.gz.
For 403/429, wait and retry or authenticate the download (e.g. set GITHUB_TOKEN if the fetch supports it); check rate-limit headers.
Verify network/proxy settings (HTTPS_PROXY etc.) and that the download host is reachable with curl.
As an alternative, build/serve the web UI locally instead of downloading it, if your install supports that path.

Example fix

// before
const res = await fetch(tarballUrl); // no status handling, throws raw error at serve time
// after
const res = await fetch(tarballUrl);
if (!res.ok) {
  if (res.status === 403 || res.status === 429) {
    // back off and retry once with auth/rate-limit awareness
  }
  throw new Error(`Failed to download web UI: ${res.status} ${res.statusText}`);
}

Defensive patterns

Strategy: try-catch

Validate before calling

const probe = await fetch(tarballUrl, { method: 'HEAD' });
if (!probe.ok) {
  throw new Error(`web UI tarball unavailable: HTTP ${probe.status}; check release exists and rate limits`);
}

Try / catch

try {
  await serveCommand();
} catch (err) {
  if (err instanceof Error && err.message.startsWith('Failed to download web UI:')) {
    const status = Number(err.message.match(/: (\d+)/)?.[1]);
    if (status === 403 || status === 429) {
      // wait/back off or supply auth, then retry
    } else if (status === 404) {
      // pin/upgrade CLI version whose release has the asset
    }
  } else throw err;
}

Prevention

Pin the CLI to releases you have verified publish archon-web.tar.gz.
Configure download auth/credentials before hitting rate limits on large registries.
Pre-warm the download (or vendor the artifact locally) before running serve in CI or air-gapped environments.
Monitor the download host with a HEAD request in deploy scripts.

When it happens

Trigger: serveCommand -> downloadWebDist performs a fetch of the web UI tarball; the response arrives but response.ok is false — e.g. 404 (release asset missing or version tag wrong), 403 (rate limited by the host or private repo), 5xx (server error), or a proxy returning an error page.

Common situations: Running a CLI version that references a release whose web tarball was not published or was deleted; GitHub rate limiting unauthenticated requests (403); corporate proxy returning 403/502; offline DNS-captive portal returning an HTML error page with a 4xx/5xx status; wrong download URL in configuration.

Related errors

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