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

_download_and_extract_archive() fetches the .sha256 sidecar from the GitHub release URL before downloading the archive, so it never extracts an unverified file. If client.get(sha256_url) raises (raise_for_status() on non-2xx, timeout, DNS, or any other exception) the except block re-raises as RuntimeError chained from the original. The client is created with timeout=30.0 in download_cuda_binary().

Source

Thrown at backend/services/cuda.py:199

        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. Verify the release page for the version tag actually has the .sha256 asset uploaded.
2. Retry — transient GitHub/network errors frequently clear on the next attempt.
3. Confirm github.com is reachable (no proxy/firewall block) from the host.
4. Ensure the version passed to download_cuda_binary matches an existing published release tag.

Example fix

# before
sha_resp = await client.get(sha256_url)
sha_resp.raise_for_status()

# after — surface HTTP status for diagnosis
sha_resp = await client.get(sha256_url)
if sha_resp.status_code != 200:
    raise RuntimeError(f"{label}: checksum HTTP {sha_resp.status_code} at {sha256_url}")
sha_resp.raise_for_status()

import httpx

async def checksum_reachable(base_url: str, archive: str) -> bool:
    async with httpx.AsyncClient(timeout=10.0) as c:
        r = await c.head(f"{base_url}/{archive}.sha256")
        return r.status_code == 200

for attempt in range(3):
    try:
        await download_cuda_binary(version)
        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: The .sha256 asset wasn't uploaded for the target release tag (404), transient network outage or DNS failure reaching github.com, GitHub rate-limiting, a proxy/firewall blocking the release-download domain, or the 30s httpx timeout elapsings on a slow link.

Common situations: A release tag missing the .sha256 sidecar artifact; corporate proxy blocking github.com; first CUDA backend download on a constrained Windows machine; typo'd/custom version argument pointing at a non-existent release.

Related errors

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

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