XX-net/XX-Net · error · Exception

downloaded xxnet zip checksum fail

Error message

downloaded xxnet zip checksum fail:%s

What it means

Exception raised when hash verification of the downloaded XX-Net zip fails: get_hash_sum(version) returns the expected digest and hash_file_sum(zip) mismatches it. This means the archive is corrupted (or, rarely, tampered) — e.g. a truncated download that didn't hit the time budget or HTML error content saved as the zip.

Solutions

  1. Delete the partial zip in the download path and retry the update
  2. Verify manually: compare sha256 of the zip against the published hash_sum file
  3. If the official hash itself is wrong (release re-tag), wait for maintainers or update manually from the GitHub release page
  4. Check for middlebox/proxy interference by downloading via browser and comparing
Defensive patterns

Strategy: fallback

Validate before calling

import os, hashlib
def zip_intact(zip_path, expected_sha256):
    if not os.path.exists(zip_path):
        return False
    h = hashlib.sha256(open(zip_path,'rb').read()).hexdigest()
    return h == expected_sha256

Try / catch

try:
    update_version(new_version)
except Exception as e:
    if 'checksum fail' in str(e):
        os.remove(zip_path)  # corrupted download
        try:
            update_version(new_version)
        except Exception:
            manual_update_from_release_page(new_version)
    else:
        raise

Prevention

When it happens

Trigger: update_version -> download_overwrite_new_version with checkhash enabled, where download_file 'succeeded' (stream ended) but the bytes differ from the published hash — truncated file, hijacked download, or hash manifest mismatch after a release re-tag.

Common situations: Silent corruption on flaky links, ISP/middlebox injecting error pages into the download, release re-uploaded with stale hash manifest, proxy mangling content.

Understand the failure class

Background: Checksum mismatch errors: "checksum verification failed", "digest mismatch", "expected vs actual checksum" — what they mean and how to fix them — this error's family across 41 libraries.

Related errors

AI-assisted analysis of XX-net/XX-Net@cfa5bc17b6 (2026-08-27). Data as JSON: /api/errors/622c56392f5ce50d. Report an issue: GitHub.

Appendix: source

Thrown at code/default/launcher/update_from_github.py:295

def download_overwrite_new_version(xxnet_version, checkhash=1):
    global update_progress

    xxnet_url = 'https://codeload.github.com/XX-net/XX-Net/zip/%s' % xxnet_version
    xxnet_zip_file = os.path.join(download_path, "XX-Net-%s.zip" % xxnet_version)
    xxnet_unzip_path = os.path.join(download_path, "XX-Net-%s" % xxnet_version)

    progress["update_status"] = "Downloading %s" % xxnet_url
    if not download_file(xxnet_url, xxnet_zip_file):
        progress["update_status"] = "Download Fail."
        raise Exception("download xxnet zip fail:%s" % xxnet_zip_file)

    if checkhash:
        hash_sum = get_hash_sum(xxnet_version)
        if len(hash_sum) and hash_file_sum(xxnet_zip_file) != hash_sum:
            progress["update_status"] = "Download Checksum Fail."
            xlog.warn("downloaded xxnet zip checksum fail:%s" % xxnet_zip_file)
            raise Exception("downloaded xxnet zip checksum fail:%s" % xxnet_zip_file)
    else:
        xlog.debug("skip checking downloaded file hash")

    xlog.info("update download %s finished.", download_path)

    xlog.info("update start unzip")
    progress["update_status"] = "Unziping"
    try:
        with zipfile.ZipFile(xxnet_zip_file, "r") as dz:
            dz.extractall(download_path)
            dz.close()
    except Exception as e:
        xlog.warn("unzip %s fail:%r", xxnet_zip_file, e)
        progress["update_status"] = "Unzip Fail:%s" % e
        raise e
    xlog.info("update finished unzip")

    overwrite(xxnet_version, xxnet_unzip_path)

View on GitHub (pinned to cfa5bc17b6)