microsoft/aspire · error · InvalidOperationException

Aspire skills bundle version

Error message

Aspire skills bundle version '{0}' does not match expected version '{1}'.

What it means

ValidateBundleVersion compares the version embedded in a downloaded/unpacked Aspire skills bundle against the version the CLI expected. A mismatch means the bundle metadata does not describe the bundle that was requested — typically a corrupted, stale, or tampered cache/payload. The installer aborts rather than installing a bundle that may be from a different CLI release.

Solutions

Clear the Aspire skills cache directory shown in the error and re-run the command so a fresh, matching bundle is staged.
Verify the installed CLI version matches the bundle version expected (aspire --version) and upgrade or downgrade the CLI accordingly.
Re-download/reinstall the skills bundle if using an explicit bundle source; the archive may be corrupt or from another channel.
If running daily vs stable channels, ensure you are not mixing cache between channels.

Example fix

// before
# stale cache after CLI upgrade
aspire skills install  // version '9.4.0' vs expected '9.5.0'
// after
rm -rf ~/.aspire/skills/cache
aspire skills install  // re-stages bundle matching current CLI

Defensive patterns

Strategy: fallback

Try / catch

try
{
    await installer.InstallAsync(...);
}
catch (InvalidOperationException ex) when (ex.Message.Contains("does not match expected version"))
{
    // delete the stale cache directory and retry to force a fresh bundle
}

Prevention

Clear the skills cache after upgrading or switching the CLI channel.
Do not share one cache directory across daily/stable CLI builds.
Re-run the install command after any interrupted (killed) install.

When it happens

Trigger: Thrown by ValidateBundleVersion when bundle.Version is not equal (case-insensitive) to expectedVersion — i.e. the bundle loaded from cache or extracted from an embedded/downloaded archive declares a different version than the running CLI requires.

Common situations: A stale cache directory survives a CLI upgrade or downgrade; the bundle archive was corrupted or partially extracted; a cached bundle from a prerelease/daily channel is reused by a stable build; manual edits or copies of the cache directory.

Related errors

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

Appendix: source

Thrown at src/Aspire.Cli/Agents/AspireSkills/AspireSkillsInstaller.cs:924

    internal static bool IsCacheLockContention(IOException exception, bool isWindows)
    {
        if (isWindows)
        {
            return exception.HResult is WindowsSharingViolationHResult or WindowsLockViolationHResult;
        }

        // On Unix, FileStream implements FileShare.None with a non-blocking flock and exposes
        // EWOULDBLOCK as the raw errno in IOException.HResult: 11 on Linux and 35 on macOS.
        // See https://github.com/dotnet/runtime/blob/main/src/libraries/System.Private.CoreLib/src/Microsoft/Win32/SafeHandles/SafeFileHandle.Unix.cs.
        return exception.HResult is LinuxWouldBlockHResult or MacOsWouldBlockHResult;
    }

    private static void ValidateBundleVersion(AspireSkillsBundle bundle, string expectedVersion)
    {
        if (!string.Equals(bundle.Version, expectedVersion, StringComparison.OrdinalIgnoreCase))
        {
            throw new InvalidOperationException(string.Format(
                CultureInfo.InvariantCulture,
                "Aspire skills bundle version '{0}' does not match expected version '{1}'.",
                bundle.Version,
                expectedVersion));
        }
    }

    private static string ComputeArchiveSha256(string archivePath)
    {
        using var stream = File.OpenRead(archivePath);
        return Convert.ToHexString(SHA256.HashData(stream)).ToLowerInvariant();
    }

    private static string ComputeArchiveSha512(string archivePath)
    {
        using var stream = File.OpenRead(archivePath);
        return Convert.ToHexString(SHA512.HashData(stream)).ToLowerInvariant();
    }

View on GitHub (pinned to 25830f84bd)