jamiepine/voicebox · error · RuntimeError

{label}: failed to fetch checksum from {sha256_url}

Error message

{label}: failed to fetch checksum from {sha256_url}

What it means

Raised by the ROCm archive download helper when fetching the .sha256 checksum file from sha256_url fails — client.get() or raise_for_status() threw. The helper is fail-fast: it refuses to download or extract an archive whose expected checksum could not be retrieved, since extracting an unverified archive is unsafe. The original exception is chained via 'from e'.

Source

Thrown at backend/services/rocm.py:176

        total_size: Total bytes across all downloads (for progress bar)
    """
    progress = get_progress_manager()
    temp_path = dest_dir / f".download-{label.replace(' ', '-')}.tmp"

    # Clean up leftover partial download
    if temp_path.exists():
        temp_path.unlink()

    # Fetch expected checksum (fail-fast: never extract an unverified archive)
    expected_sha = None
    if sha256_url:
        try:
            sha_resp = await client.get(sha256_url)
            sha_resp.raise_for_status()
            expected_sha = sha_resp.text.strip().split()[0]
            logger.info(f"{label}: expected SHA-256: {expected_sha[:16]}...")
        except Exception as e:
            raise RuntimeError(f"{label}: failed to fetch checksum from {sha256_url}") from e

    # Stream download, verify, and extract — always clean up temp file
    downloaded = 0
    try:
        async with client.stream("GET", url) as response:
            response.raise_for_status()
            with open(temp_path, "wb") as f:
                async for chunk in response.aiter_bytes(chunk_size=1024 * 1024):
                    f.write(chunk)
                    downloaded += len(chunk)
                    progress.update_progress(
                        PROGRESS_KEY,
                        current=progress_offset + downloaded,
                        total=total_size,
                        filename=f"Downloading {label}",
                        status="downloading",
                    )

View on GitHub (pinned to 51f49dea19)

Solutions

1. Check network connectivity and that the sha256_url resolves (curl -I <sha256_url>); retry on transient failures.
2. Verify the ROCm version maps to an existing release with both the .tar.gz and .sha256 assets published.
3. If behind a proxy, set HTTPS_PROXY and ensure the proxy allows the GitHub release domain.
4. For air-gapped setups, host the archive and checksum on an internal mirror and point the download URLs there.
5. If checksum verification is intentionally skipped, call the downloader without a sha256_url (expected_sha stays None).

Example fix

// before: raises because checksum fetch 404s
// after: verify asset exists, or run without checksum
# confirm the URL
# curl -I https://github.com/.../rocm-6.1.tar.gz.sha256
# then retry; or call the helper with sha256_url=None to skip verification

import httpx

async def checksum_url_reachable(client: httpx.AsyncClient, sha256_url: str) -> bool:
    try:
        r = await client.get(sha256_url)
        return r.status_code == 200
    except Exception:
        return False

for attempt in range(3):
    try:
        await download_verified_archive(client, url, sha256_url, dest_dir, label)
        break
    except RuntimeError as e:
        if 'failed to fetch checksum' in str(e) and attempt < 2:
            await asyncio.sleep(2 ** attempt)
            continue
        raise

When it happens

Trigger: Network outage or DNS failure reaching the GitHub-hosted .sha256 URL; the checksum URL returns 404/5xx (release asset missing or renamed); a proxy/firewall blocks the request; TLS/cert error; transient timeout.

Common situations: Corporate proxy blocking raw GitHub release downloads; GitHub release asset renamed so the sha256 file moved; offline/air-gapped install attempting to reach the internet; transient GitHub outage during setup; expired CDN link.

Related errors

• {label} integrity check failed: expected {expected_sha[:16]}
• {label}: failed to fetch checksum from {sha256_url}
• HTTP error! status: ${response.status}
• releases ${r.status}
• ROCm backend download already in progress

AI-assisted analysis of jamiepine/voicebox@51f49dea19 (2026-08-12). Data as JSON: /api/errors/07b0664d4003a416. Report an issue: GitHub.