microsoft/aspire · error · AppHostIncompatibleException

The AppHost does not support --list-steps. Update the…

Error message

The AppHost does not support --list-steps. Update the AppHost to a newer version of Aspire.

What it means

When 'aspire pipeline --list-steps' runs, the CLI checks the AppHost project's Aspire.Hosting version via GetAspireHostingVersionAsync. If IsKnownIncompatibleWithListSteps reports the version predates the capability, it throws AppHostIncompatibleException stating the AppHost must be updated to a newer Aspire version to support --list-steps.

Solutions

1. Update the AppHost project's Aspire.Hosting.* package references to a version compatible with --list-steps (e.g. 'dotnet add package Aspire.Hosting')
2. Run 'aspire update' in the AppHost directory to bump Aspire packages
3. Drop --list-steps if staying on the older AppHost version

Example fix

// before
<PackageReference Include="Aspire.Hosting" Version="9.0.0" />
// after
<PackageReference Include="Aspire.Hosting" Version="9.5.0" /> <!-- version supporting --list-steps -->

var version = await project.GetAspireHostingVersionAsync(appHostFile, ct);
if (Version.TryParse(version, out var v) && v < new Version("9.3.0"))
{
    Console.Error.WriteLine($"AppHost uses Aspire.Hosting {version}; --list-steps needs a newer version. Run 'aspire update'.");
    return 1;
}

try
{
    await pipelineCommand.ExecuteAsync(...);
}
catch (AppHostIncompatibleException ex)
{
    Console.Error.WriteLine($"{ex.Message} (current: {ex.CurrentVersion}). Update Aspire.Hosting packages.");
}

When it happens

Trigger: Executing 'aspire pipeline --list-steps' against an AppHost project whose referenced Aspire.Hosting package version is known to be incompatible with the ListSteps capability.

Common situations: Older Aspire AppHost template projects (pinned to older Aspire.Hosting versions) used with a newer CLI; solution with mixed package versions where the target AppHost lags the CLI.

Related errors

• Aspire Extension is incompatible with the CLI. The…
• Run completed without returning a backchannel.
• Step ' ' not found in pipeline. Available steps
• Step ' ' not found for task
• A step with the name

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

Appendix: source

Thrown at src/Aspire.Cli/Commands/PipelineCommandBase.cs:237

            using var activity = Telemetry.StartDiagnosticActivity(this.Name);

            var searchResult = await _projectLocator.UseOrFindAppHostProjectFileAsync(passedAppHostProjectFile, MultipleAppHostProjectsFoundBehavior.Prompt, createSettingsFile: true, cancellationToken);
            var effectiveAppHostFile = searchResult.SelectedProjectFile;

            if (effectiveAppHostFile is null)
            {
                // Send terminal progress bar stop sequence
                StopTerminalProgressBar();
                return CommandResult.Failure(CliExitCodes.FailedToFindProject);
            }

            var project = _projectFactory.GetProject(effectiveAppHostFile);
            if (listSteps)
            {
                var aspireHostingVersion = await project.GetAspireHostingVersionAsync(effectiveAppHostFile, cancellationToken);
                if (IsKnownIncompatibleWithListSteps(aspireHostingVersion))
                {
                    throw new AppHostIncompatibleException(
                        ListStepsIncompatibleMessage,
                        ListStepsCapability,
                        aspireHostingVersion);
                }
            }

            var env = new Dictionary<string, string>
            {
                [KnownConfigNames.AspireHome] = ExecutionContext.AspireHomeDirectory.FullName
            };

            // Set interactivity enabled based on host environment capabilities
            if (!_hostEnvironment.SupportsInteractiveInput)
            {
                env[KnownConfigNames.InteractivityEnabled] = "false";
            }

            if (waitForDebugger)

View on GitHub (pinned to 25830f84bd)