LykosAI/StabilityMatrix · error · Exception

Python download hash mismatch: expected , actual

Error message

Python {version} download hash mismatch: expected {hashSha256}, actual {actualHash}

What it means

InstallPythonIfNecessary downloads a Python tarball for Unix and verifies its SHA-256 against an expected hash; a mismatch (corrupted, truncated, or replaced download) throws a plain Exception with expected vs actual hashes. This prevents extracting a tampered or incomplete Python distribution.

Solutions

Delete the bad tar.gz from the Assets directory and retry the Python install on a stable connection.
Check for proxy/VPN/firewall interference that could alter or truncate the download.
Free disk space and ensure the app has write access to the assets path.
If the upstream hash changed, update Stability Matrix (the expected hash ships with the app).

Defensive patterns

Strategy: retry

Validate before calling

var expected = ExpectedHashes[version];
var actual = await FileHash.GetSha256Async(downloadPath);
if (actual != expected) File.Delete(downloadPath); // force re-download

Try / catch

try { await helper.InstallPythonIfNecessary(version); }
catch (Exception ex) when (ex.Message.Contains("hash mismatch"))
{ logger.Warn("Python download corrupted; deleting and retrying..."); File.Delete(downloadPath); await RetryWithBackoff(); }

Prevention

Use a stable wired connection for large downloads.
Exclude the app's download path from proxy/AV interception.
Ensure sufficient free disk space before downloading.
Update Stability Matrix when upstream hashes change.

When it happens

Trigger: SHA-256 of the downloaded python-{version}-amd64.tar.gz differs from hashSha256 — download interrupted mid-stream, server/proxy returning an error page instead of the archive, or a mirrored file changed upstream.

Common situations: Flaky network or captive portal truncating large downloads; corporate proxy substituting content; CDN serving stale/partial file; disk full silently corrupting the written file.

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 LykosAI/StabilityMatrix@af93d6ef57 (2026-09-12). Data as JSON: /api/errors/402d426e8170f18a. Report an issue: GitHub.

Appendix: source

Thrown at StabilityMatrix.Avalonia/Helpers/UnixPrerequisiteHelper.cs:342

        // Download
        var remote = GetPythonDownloadResource(version);
        var url = remote.Url;
        var hashSha256 = remote.HashSha256;

        var fileName = Path.GetFileName(url.LocalPath);
        var downloadPath = Path.Combine(AssetsDir, fileName);
        Logger.Info($"Downloading Python {version} from {url} to {downloadPath}");
        try
        {
            await downloadService.DownloadToFileAsync(url.ToString(), downloadPath, progress);

            // Verify hash
            var actualHash = await FileHash.GetSha256Async(downloadPath);
            Logger.Info($"Verifying Python {version} hash: (expected: {hashSha256}, actual: {actualHash})");
            if (actualHash != hashSha256)
            {
                throw new Exception(
                    $"Python {version} download hash mismatch: expected {hashSha256}, actual {actualHash}"
                );
            }

            // Extract
            Logger.Info($"Extracting Python {version} Zip: {downloadPath} to {pythonDir}");
            if (pythonDir.Exists)
            {
                await pythonDir.DeleteAsync(true);
            }
            progress?.Report(new ProgressReport(0, $"Installing Python {version}", isIndeterminate: true));
            await ArchiveHelper.Extract7ZAuto(downloadPath, pythonDir);

            // For Unix, move the inner 'python' folder up to the root PythonDir
            if (Compat.IsUnix)
            {
                var innerPythonDir = pythonDir.JoinDir("python");
                if (!innerPythonDir.Exists)

View on GitHub (pinned to af93d6ef57)