usestrix/strix · critical · RuntimeError

checksum mismatch for {filename}: expected sha256 {expected_

Error message

checksum mismatch for {filename}: expected sha256 {expected_digest}, got {actual_digest}

What it means

Raised during self-update (_download_and_replace, update_check.py:311) when the sha256 of the downloaded release archive does not match the digest published for that asset. Strix fetches the expected digest via _fetch_asset_digest(version, filename), hashes the downloaded file with _sha256_file, and treats any mismatch as a corrupt or tampered download, aborting before extraction and binary replacement. If no digest is published, verification is skipped with a warning instead.

Source

Thrown at strix/interface/update_check.py:311

    with tempfile.TemporaryDirectory() as tmp:
        tmp_dir = Path(tmp)
        archive_path = tmp_dir / filename
        console.print(f"[dim]Downloading[/] {url}")
        with requests.get(  # nosec B113
            url,
            stream=True,
            timeout=REQUEST_TIMEOUT_SECONDS * 12,
        ) as response:
            response.raise_for_status()
            with archive_path.open("wb") as f:
                for chunk in response.iter_content(chunk_size=1 << 20):
                    f.write(chunk)

        expected_digest = _fetch_asset_digest(version, filename)
        if expected_digest:
            actual_digest = _sha256_file(archive_path)
            if actual_digest != expected_digest:
                raise RuntimeError(
                    f"checksum mismatch for {filename}: "
                    f"expected sha256 {expected_digest}, got {actual_digest}"
                )
        else:
            console.print("[dim yellow]No published checksum available; skipping verification[/]")

        if is_windows:
            with zipfile.ZipFile(archive_path) as zf:
                zf.extract(binary_name, tmp_dir)
        else:
            with tarfile.open(archive_path, "r:gz") as tf:
                tf.extract(binary_name, tmp_dir, filter="data")

        new_binary = tmp_dir / binary_name
        new_binary.chmod(new_binary.stat().st_mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)

        staged = current_exe.with_name(current_exe.name + ".new")
        try:

View on GitHub (pinned to 8551339130)

Solutions

  1. Re-run the update on a stable network — a clean re-download fixes most truncation cases
  2. Compare manually: download the archive and its checksum asset, run sha256sum, and inspect which side differs
  3. Disable/inspect HTTP-intercepting proxies or AV for github.com release downloads
  4. Ensure temp dir space is sufficient (archive is written to a TemporaryDirectory)
  5. If the published digest itself is wrong (re-uploaded release), wait for maintainers or pin the previous version

Example fix

# before
# 'y' at update prompt over flaky wifi -> checksum mismatch

# after
curl -LO https://github.com/<repo>/releases/download/vX.Y.Z/strix-X.Y.Z-linux-x86_64.tar.gz
sha256sum strix-X.Y.Z-linux-x86_64.tar.gz  # verify manually
# then re-run strix and accept the update on a stable link
Defensive patterns

Strategy: retry

Validate before calling

expected = _fetch_asset_digest(version, filename)
if expected:
    actual = _sha256_file(archive_path)
    assert actual == expected, "corrupt download; retry on a stable link"

Type guard

def digest_matches(path, expected: str | None) -> bool:
    return expected is None or _sha256_file(path) == expected

Try / catch

for attempt in range(2):
    try:
        self_update(console, version=latest)
        break
    except RuntimeError as e:
        if "checksum mismatch" in str(e) and attempt == 0:
            continue  # re-download once: truncation is the usual cause
        raise

Prevention

When it happens

Trigger: Answering 'y' to the update prompt for a binary install while the GitHub release download was truncated or corrupted (network interruption, MITM/proxy rewriting, disk-full during write), or the published checksum file changed mid-release. The temp-dir archive is hashed and compared before any extraction.

Common situations: Flaky connection truncating the tarball/zip; corporate proxy or AV stripping/modifying content; a partially-overwritten release asset during publishing; disk-full causing a short write; clock/race when a release was re-uploaded while updating.

Related errors

AI-assisted analysis of usestrix/strix@8551339130 (2026-08-15). Data as JSON: /api/errors/8933fe9a55d985d9. Report an issue: GitHub.