LykosAI/StabilityMatrix · error · Exception

Hash validation for failed, expected but got

Error message

Hash validation for {FileName} failed, expected {ExpectedHashSha256} but got {hash}

What it means

TrackedDownload verifies the completed download by SHA-256 against ExpectedHashSha256. If the computed hash differs, it throws, aborting the download before the temp file is promoted to its final name. This protects against corrupted or tampered downloads.

Solutions

1. Delete the downloaded temp file and restart the download from the original source.
2. Verify the expected hash matches the file version actually hosted (model may have been updated upstream).
3. Retry with a different mirror or direct URL.
4. Check network path for proxies/CDNs that may alter content.

Example fix

// before
throw new Exception($"Hash validation for {FileName} failed, expected {ExpectedHashSha256} but got {hash}");
// after
throw new HashMismatchException(FileName, ExpectedHashSha256, hash)
{
    SuggestedAction = SuggestedAction.RestartDownload
};

// Pre-check the source integrity if the server supports checksums
var expected = download.ExpectedHashSha256?.ToLowerInvariant();
if (string.IsNullOrEmpty(expected))
    _logger.LogWarning("No expected hash for {FileName}; integrity cannot be verified", download.FileName);

try { await trackedDownload.Start(); }
catch (Exception ex) when (ex.Message.Contains("Hash validation"))
{
    _logger.LogError(ex, "Checksum mismatch for {File}", trackedDownload.FileName);
    await trackedDownload.Cancel();
    await downloads.TryRestartFromAlternateMirror(trackedDownload);
}

When it happens

Trigger: Start or Resume leading StartDownloadTask to hash a finished file whose SHA-256 does not match the expected value (case-insensitive compare against lowercased expectation).

Common situations: Mirror serving different file versions than the manifest hash, interrupted/truncated downloads that still completed, file updated upstream after hash was recorded, proxy/CDN corruption.

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

• Python download hash mismatch: expected , actual
• Could not find file
• Expected SageAttention file
• Not enough free space to download file. Free
• Response is null

AI-assisted analysis of LykosAI/StabilityMatrix@af93d6ef57 (2026-09-12). Data as JSON: /api/errors/37720d9e326e9383. Report an issue: GitHub.

Appendix: source

Thrown at StabilityMatrix.Core/Models/TrackedDownload.cs:157

            .ResumeDownloadToFileAsync(
                SourceUrl.ToString(),
                DownloadDirectory.JoinFile(TempFileName),
                resumeFromByte,
                progress,
                cancellationToken: cancellationToken
            )
            .ConfigureAwait(false);

        // If hash validation is enabled, validate the hash
        if (ValidateHash)
        {
            OnProgressUpdate(new ProgressReport(0, isIndeterminate: true, type: ProgressType.Hashing));
            var hash = await FileHash
                .GetSha256Async(DownloadDirectory.JoinFile(TempFileName), progress)
                .ConfigureAwait(false);
            if (hash != ExpectedHashSha256?.ToLowerInvariant())
            {
                throw new Exception(
                    $"Hash validation for {FileName} failed, expected {ExpectedHashSha256} but got {hash}"
                );
            }
        }

        // Rename the temp file to the final file
        var tempFile = DownloadDirectory.JoinFile(TempFileName);
        var finalFile = tempFile.Rename(FileName);

        // If auto-extract is enabled, extract the archive
        if (AutoExtractArchive)
        {
            OnProgressUpdate(new ProgressReport(0, isIndeterminate: true, type: ProgressType.Extract));

            var extractDirectory = string.IsNullOrWhiteSpace(ExtractRelativePath)
                ? DownloadDirectory
                : DownloadDirectory.JoinDir(ExtractRelativePath);

View on GitHub (pinned to af93d6ef57)