XX-net/XX-Net · error · Exception

downloaded xxnet zip checksum fail:%s

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.

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)

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.

Related errors

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