microsoft/aspire · error · InvalidOperationException

Aspire skills bundle was not resolved for skill

Error message

Aspire skills bundle was not resolved for skill '{skill.Name}'.

What it means

AgentInitCommand throws this InvalidOperationException when a skill declares SkillSourceKind.AspireSkillsBundle, but the aspireSkillsBundle instance was never resolved and passed into GetSkillFilesAsync. It is a guard against an internally inconsistent state: the skill claims to come from the Aspire skills bundle, yet no bundle is available to fetch its files from.

Solutions

Ensure the Aspire skills bundle is resolved (downloaded/cached) before enumerating skills, and skip bundle-sourced skills if resolution fails
Check why aspireSkillsBundle was null: fix the resolution step so it either throws early with a clear message or filters out AspireSkillsBundle skills
Update the Aspire CLI to the latest version in case bundle resolution had a bug

Example fix

// before
if (aspireSkillsBundle is null)
{
    throw new InvalidOperationException($"Aspire skills bundle was not resolved for skill '{skill.Name}'.");
}
// after
if (aspireSkillsBundle is null)
{
    _logger.LogWarning("Skipping skill '{SkillName}': Aspire skills bundle is unavailable.", skill.Name);
    return null; // or filter such skills before calling GetSkillFilesAsync
}

Defensive patterns

Strategy: validation

Validate before calling

if (skill.SourceKind is SkillSourceKind.AspireSkillsBundle && aspireSkillsBundle is null)
{
    throw new InvalidOperationException($"Aspire skills bundle must be resolved before installing '{skill.Name}'.");
}

Type guard

if (skill.SourceKind is SkillSourceKind.AspireSkillsBundle && aspireSkillsBundle is null) { /* skip or resolve first */ }

Try / catch

try
{
    await GetSkillFilesAsync(skill, bundle, ct);
}
catch (InvalidOperationException ex) when (ex.Message.Contains("skills bundle was not resolved"))
{
    logger.LogWarning(ex, "Skipping skill {Skill}: bundle unavailable", skill.Name);
}

Prevention

Resolve the skills bundle before enumerating/installing skills
Filter out AspireSkillsBundle skills when the bundle is null
Log bundle resolution failures early instead of passing null downstream

When it happens

Trigger: Calling GetSkillFilesAsync (via skillFiles) with a skill whose SourceKind is AspireSkillsBundle while the aspireSkillsBundle argument is null — e.g. bundle resolution/discovery failed or was skipped earlier in the command pipeline but the skill list still contains bundle-sourced skills.

Common situations: Running 'aspire agent init' with skills configured from the Aspire skills bundle when the bundle was not downloaded, not found, or an earlier resolution step silently returned null; corrupted or missing bundle cache.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

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

Appendix: source

Thrown at src/Aspire.Cli/Commands/AgentInitCommand.cs:765

        var displayRelativeSkillDirectory = relativeSkillDirectory
            .Replace(Path.DirectorySeparatorChar, '/')
            .Replace(Path.AltDirectorySeparatorChar, '/');

        return isUserLevel ? $"~/{displayRelativeSkillDirectory}" : displayRelativeSkillDirectory;
    }

    private static async Task<IReadOnlyList<SkillAssetFile>> GetSkillFilesAsync(SkillDefinition skill, AspireSkillsBundle? aspireSkillsBundle, CancellationToken cancellationToken)
    {
        if (skill.SkillContent is not null)
        {
            return [new SkillAssetFile("SKILL.md", skill.SkillContent)];
        }

        if (skill.SourceKind is SkillSourceKind.AspireSkillsBundle)
        {
            if (aspireSkillsBundle is null)
            {
                throw new InvalidOperationException($"Aspire skills bundle was not resolved for skill '{skill.Name}'.");
            }

            return await aspireSkillsBundle.GetSkillFilesAsync(skill, cancellationToken);
        }

        throw new InvalidOperationException($"Skill '{skill.Name}' does not define installable files.");
    }

    private sealed record InstalledSkillSummaryItem(string SkillName, string DisplayLocation);

    private readonly record struct SkillInstallResult(bool Succeeded, InstalledSkillSummaryItem? UpdatedSkill);
}

internal readonly record struct AgentInitExecutionResult(
    int ExitCode,
    IReadOnlyList<SkillLocation> SelectedLocations,
    IReadOnlyList<SkillDefinition> SelectedSkills);

View on GitHub (pinned to 25830f84bd)