{"record":{"id":"622c56392f5ce50d","repo":"XX-net/XX-Net","slug":"downloaded-xxnet-zip-checksum-fail-s","errorCode":null,"errorMessage":"downloaded xxnet zip checksum fail:%s","messagePattern":"downloaded xxnet zip checksum fail:(.+?)","errorType":"exception","errorClass":"Exception","httpStatus":null,"severity":"error","filePath":"code/default/launcher/update_from_github.py","lineNumber":295,"sourceCode":"\ndef download_overwrite_new_version(xxnet_version, checkhash=1):\n    global update_progress\n\n    xxnet_url = 'https://codeload.github.com/XX-net/XX-Net/zip/%s' % xxnet_version\n    xxnet_zip_file = os.path.join(download_path, \"XX-Net-%s.zip\" % xxnet_version)\n    xxnet_unzip_path = os.path.join(download_path, \"XX-Net-%s\" % xxnet_version)\n\n    progress[\"update_status\"] = \"Downloading %s\" % xxnet_url\n    if not download_file(xxnet_url, xxnet_zip_file):\n        progress[\"update_status\"] = \"Download Fail.\"\n        raise Exception(\"download xxnet zip fail:%s\" % xxnet_zip_file)\n\n    if checkhash:\n        hash_sum = get_hash_sum(xxnet_version)\n        if len(hash_sum) and hash_file_sum(xxnet_zip_file) != hash_sum:\n            progress[\"update_status\"] = \"Download Checksum Fail.\"\n            xlog.warn(\"downloaded xxnet zip checksum fail:%s\" % xxnet_zip_file)\n            raise Exception(\"downloaded xxnet zip checksum fail:%s\" % xxnet_zip_file)\n    else:\n        xlog.debug(\"skip checking downloaded file hash\")\n\n    xlog.info(\"update download %s finished.\", download_path)\n\n    xlog.info(\"update start unzip\")\n    progress[\"update_status\"] = \"Unziping\"\n    try:\n        with zipfile.ZipFile(xxnet_zip_file, \"r\") as dz:\n            dz.extractall(download_path)\n            dz.close()\n    except Exception as e:\n        xlog.warn(\"unzip %s fail:%r\", xxnet_zip_file, e)\n        progress[\"update_status\"] = \"Unzip Fail:%s\" % e\n        raise e\n    xlog.info(\"update finished unzip\")\n\n    overwrite(xxnet_version, xxnet_unzip_path)","sourceCodeStart":277,"sourceCodeEnd":313,"githubUrl":"https://github.com/XX-net/XX-Net/blob/cfa5bc17b67676e467f37ec50766127e0ab5f0aa/code/default/launcher/update_from_github.py#L277-L313","documentation":"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.","triggerScenarios":"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.","commonSituations":"Silent corruption on flaky links, ISP/middlebox injecting error pages into the download, release re-uploaded with stale hash manifest, proxy mangling content.","solutions":["Delete the partial zip in the download path and retry the update","Verify manually: compare sha256 of the zip against the published hash_sum file","If the official hash itself is wrong (release re-tag), wait for maintainers or update manually from the GitHub release page","Check for middlebox/proxy interference by downloading via browser and comparing"],"exampleFix":null,"handlingStrategy":"fallback","validationCode":"import os, hashlib\ndef zip_intact(zip_path, expected_sha256):\n    if not os.path.exists(zip_path):\n        return False\n    h = hashlib.sha256(open(zip_path,'rb').read()).hexdigest()\n    return h == expected_sha256","typeGuard":null,"tryCatchPattern":"try:\n    update_version(new_version)\nexcept Exception as e:\n    if 'checksum fail' in str(e):\n        os.remove(zip_path)  # corrupted download\n        try:\n            update_version(new_version)\n        except Exception:\n            manual_update_from_release_page(new_version)\n    else:\n        raise","preventionTips":["Always delete the corrupt zip before re-running the updater","Compare sha256 manually against the published hash_sum when verification fails","Be alert to middlebox interference if checksums fail repeatedly on one network"],"tags":["launcher","update","checksum","integrity"],"backgroundTag":"checksum-mismatch","analyzedSha":"cfa5bc17b67676e467f37ec50766127e0ab5f0aa","analyzedAt":"2026-08-27T19:28:28.225Z","schemaVersion":2},"datasetVersion":"2026-08-28T00:17:15.603Z"}