microsoft/aspire · error · InvalidOperationException

Aspire skills bundle manifest must specify supported Aspire…

Error message

Aspire skills bundle manifest must specify supported Aspire versions.

What it means

ValidateCompatibility requires the bundle's skill-manifest.json to declare a 'supports' object describing compatible Aspire versions. If supports is absent (null), the provider refuses to install the bundle because it cannot verify CLI/SDK compatibility.

Solutions

1. Add a supports section with aspireCli (and optionally aspireSdk) to skill-manifest.json in the bundle
2. Regenerate the bundle using the current bundle authoring tooling so the manifest includes supports
3. Use a bundle version known to target your CLI

Example fix

// before (skill-manifest.json)
{
  "name": "my-skills"
}
// after
{
  "name": "my-skills",
  "supports": {
    "aspireCli": ">=9.0.0",
    "aspireSdk": ">=9.0.0"
  }
}

var manifest = JsonSerializer.Deserialize<SkillBundleManifest>(json);
if (manifest?.Supports is null)
    throw new InvalidOperationException("skill-manifest.json must include a 'supports' object before distribution.");

bool HasSupports(SkillBundleManifest? m) => m?.Supports is not null;

try
{
    await installer.InstallAsync(bundleRef);
}
catch (InvalidOperationException ex) when (ex.Message.Contains("must specify supported Aspire versions"))
{
    logger.LogError(ex, "Bundle manifest lacks a supports section; request a manifest update from the bundle author.");
}

When it happens

Trigger: Installing a bundle whose skill-manifest.json omits the supports node entirely; ValidateCompatibility is invoked from CreateBundle after loading the manifest.

Common situations: Hand-authored or older bundle manifests predating the supports schema, manifests copied from templates that omit optional-looking fields, or schema drift after the CLI added compatibility checking.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• Aspire skills bundle manifest must specify…
• Aspire skills bundle contains an empty version range.
• AppHost is incompatible with the CLI. The AppHost must be…
• Aspire skills bundle contains an invalid version comparator
• Aspire skills bundle contains an invalid version value

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

Appendix: source

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

        foreach (var sourceFile in Directory.GetFiles(sourceDirectory, "*", SearchOption.AllDirectories))
        {
            var relativePath = Path.GetRelativePath(sourceDirectory, sourceFile);
            var targetFile = Path.Combine(targetDirectory, relativePath);
            var targetFileDirectory = Path.GetDirectoryName(targetFile);
            if (!string.IsNullOrEmpty(targetFileDirectory))
            {
                Directory.CreateDirectory(targetFileDirectory);
            }

            File.Copy(sourceFile, targetFile, overwrite: true);
        }
    }

    private static void ValidateCompatibility(SkillBundleSupports? supports, string currentCliVersion, string currentSdkVersion)
    {
        if (supports is null)
        {
            throw new InvalidOperationException("Aspire skills bundle manifest must specify supported Aspire versions.");
        }

        if (string.IsNullOrWhiteSpace(supports.AspireCli))
        {
            throw new InvalidOperationException("Aspire skills bundle manifest must specify supports.aspireCli.");
        }

        if (!IsVersionInRange(currentCliVersion, supports.AspireCli))
        {
            throw new InvalidOperationException(string.Format(
                CultureInfo.InvariantCulture,
                "Aspire skills bundle supports Aspire CLI versions '{0}', but the current CLI version is '{1}'.",
                supports.AspireCli,
                currentCliVersion));
        }

        if (!string.IsNullOrWhiteSpace(supports.AspireSdk) &&
            !IsVersionInRange(currentSdkVersion, supports.AspireSdk))

View on GitHub (pinned to 25830f84bd)