microsoft/aspire · error · InvalidOperationException

Embedded Aspire skills archive failed SHA-512 verification…

Error message

Embedded Aspire skills archive failed SHA-512 verification. Expected '{0}', got '{1}'.

What it means

Before extracting an embedded/downloaded Aspire skills archive, ValidateArchiveSha512 recomputes the SHA-512 of the archive file and compares it to the expected hash. A mismatch means the archive is corrupted, truncated, or tampered with, so Aspire throws this InvalidOperationException and refuses to extract it.

Solutions

1. Re-download the archive (clear caches) so the bytes match the pinned SHA-512
2. Update the Aspire CLI to the version that ships the matching expected hash
3. If you publish the archive yourself, update the expectedSha512 constant to the new file's hash

Example fix

// before (pinned hash computed from an old archive)
private const string ExpectedSha512 = "aaaa...";
// after (hash of the current archive)
private const string ExpectedSha512 = "<sha512 of the republished archive>";

using var s = File.OpenRead(archivePath);
var actual = Convert.ToHexString(SHA512.HashData(s)).ToLowerInvariant();
if (actual != expectedSha512.ToLowerInvariant()) throw new Exception("Archive hash mismatch; re-download.");

try { await provider.CreateAsync(...); }
catch (InvalidOperationException ex) when (ex.Message.Contains("SHA-512 verification")) { /* delete cache and re-download archive */ }

When it happens

Trigger: AspireSkillsBundleProvider.CreateAsync downloads or materializes an archive whose computed SHA-512 differs from the expectedSha512 value bundled with the CLI.

Common situations: Interrupted or proxied downloads; a CDN or corporate proxy altering the payload; a published archive updated without updating the pinned hash; CLI version mismatch where an older CLI fetches a newer archive.

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

• Aspire skills archive entry
• Aspire skills archive entry
• Aspire skills archive entry
• Aspire skills bundle path
• Aspire skills bundle path

AI-assisted analysis of microsoft/aspire@25830f84bd (2026-09-16). Data as JSON: /api/errors/0ab67276420de0b9. Report an issue: GitHub.

Appendix: source

Thrown at src/Aspire.Cli/Agents/AspireSkills/AspireSkillsBundleProvider.cs:460

    }

    internal static string NormalizeSha256(string sha256)
    {
        return sha256.StartsWith("sha256-", StringComparison.OrdinalIgnoreCase) ||
            sha256.StartsWith("sha256:", StringComparison.OrdinalIgnoreCase)
                ? sha256[7..]
                : sha256;
    }

    private static void ValidateArchiveSha512(string archivePath, string expectedSha512)
    {
        var expectedHash = NormalizeSha512(expectedSha512);
        using var stream = File.OpenRead(archivePath);
        var actualHash = Convert.ToHexString(SHA512.HashData(stream)).ToLowerInvariant();

        if (!string.Equals(expectedHash, actualHash, StringComparison.OrdinalIgnoreCase))
        {
            throw new InvalidOperationException(string.Format(
                CultureInfo.CurrentCulture,
                AgentCommandStrings.AspireSkillsInstaller_ArchiveHashVerificationFailed,
                expectedHash,
                actualHash));
        }
    }

    private static void ExtractArchive(string archivePath, string destinationDirectory)
    {
        if (archivePath.EndsWith(".zip", StringComparison.OrdinalIgnoreCase))
        {
            ExtractZipArchive(archivePath, destinationDirectory);
            return;
        }

        ExtractTarball(archivePath, destinationDirectory);
    }

View on GitHub (pinned to 25830f84bd)