microsoft/aspire · error · InvalidOperationException

Aspire skills bundle contains an invalid version value

Error message

Aspire skills bundle contains an invalid version value '{0}'.

What it means

ParseCompatibilityVersion parses each comparator operand with SemVersion.TryParse (SemVersionStyles.Any); if the operand is not a valid semantic version, this formatted InvalidOperationException is thrown. The parsed version is then normalized to Major.Minor.Patch for comparison.

Solutions

Replace the operand with a concrete semver, e.g. '>=9.0.0' instead of '>=9.x'
Use top-level wildcard '*' rather than 'x' inside a version operand
Republish the bundle with valid semver operands

Example fix

// before
"supports": { "aspireCli": ">=9.x <10.x" }
// after
"supports": { "aspireCli": ">=9.0.0 <10.0.0" }

Defensive patterns

Strategy: validation

Validate before calling

if (!SemVersion.TryParse(operand, SemVersionStyles.Any, out _))
    throw new InvalidOperationException($"'{operand}' is not a valid semver operand; use e.g. 9.0.0.");

Type guard

bool IsValidSemVer(string? v) => v is not null && SemVersion.TryParse(v, SemVersionStyles.Any, out _);

Try / catch

try
{
    await installer.InstallAsync(bundleRef);
}
catch (InvalidOperationException ex) when (ex.Message.Contains("invalid version value"))
{
    logger.LogError(ex, "Range operand is not valid semver; replace labels like 'latest' or '9.x' with concrete versions.");
}

Prevention

Use concrete semver operands in ranges, never 'latest', '9.x', or branch names
Express any-version support via the top-level '*' wildcard only
Run a semver linter over manifest ranges before release

When it happens

Trigger: A range operand like 'latest', '9.x', 'v', or '9.0.0-' that SemVersion cannot parse is used in supports.aspireCli/aspireSdk and evaluated via IsVersionInRange.

Common situations: Using wildcard-in-operand styles such as '9.x' as an operand instead of the top-level '*' comparator, 'v'-prefixed strings the parser rejects, or branch names/labels pasted as versions.

Related errors

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

Appendix: source

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

            {
                var operand = comparator[op.Length..];
                if (string.IsNullOrWhiteSpace(operand))
                {
                    throw new InvalidOperationException(string.Format(CultureInfo.InvariantCulture, "Aspire skills bundle contains an invalid version comparator '{0}'.", comparator));
                }

                return (op, operand);
            }
        }

        return ("=", comparator);
    }

    private static SemVersion ParseCompatibilityVersion(string version)
    {
        if (!SemVersion.TryParse(version, SemVersionStyles.Any, out var parsedVersion))
        {
            throw new InvalidOperationException(string.Format(CultureInfo.InvariantCulture, "Aspire skills bundle contains an invalid version value '{0}'.", version));
        }

        return SemVersion.Parse(
            string.Create(
                CultureInfo.InvariantCulture,
                $"{parsedVersion.Major}.{parsedVersion.Minor}.{parsedVersion.Patch}"),
            SemVersionStyles.Strict);
    }
}

View on GitHub (pinned to 25830f84bd)