microsoft/aspire · error · AppHostIncompatibleException

AppHost is incompatible with the CLI. The AppHost must be…

Error message

AppHost is incompatible with the CLI. The AppHost must be updated to a version that supports the {0} capability.

What it means

During ConnectAsync, the CLI asks the AppHost for its supported backchannel capabilities and requires the baseline capability to be present. This AppHostIncompatibleException is thrown when the AppHost responds with a capability list that lacks the CLI's baseline capability, meaning the running AppHost binary predates the feature the CLI needs. The AppHost must be upgraded.

Solutions

Update the AppHost project's Aspire.Hosting.* NuGet packages (and Aspire.Sdk) to a version matching or exceeding the CLI, then rebuild and restart the AppHost.
Run `aspire update` (or `dotnet add package Aspire.Hosting --version <cli-matching-version>`) in the AppHost project.
Check for a pinned/older local CLI vs AppHost mismatch and align versions (aspire --version vs the AppHost's package version).
If using daily/stable channels, ensure the CLI channel matches the package channel used by the AppHost.

Example fix

// before
<PackageReference Include="Aspire.Hosting" Version="9.0.0" />
// after
<PackageReference Include="Aspire.Hosting" Version="9.5.0" /> <!-- matches CLI baseline -->

Defensive patterns

Strategy: try-catch

Validate before calling

// Before launching via CLI, check the AppHost's Aspire.Hosting version:
// dotnet list <AppHost>.csproj package | grep Aspire.Hosting
// ensure it is >= the CLI baseline version

Try / catch

try
{
    await backchannel.ConnectAsync(socketPath, ...);
}
catch (AppHostIncompatibleException ex)
{
    // prompt: update the AppHost's Aspire.Hosting packages to support ex capability
}

Prevention

Keep Aspire.Hosting.* package versions in lockstep with the installed aspire CLI.
Run `aspire update` after CLI upgrades before running solutions.
Avoid pinning old Aspire package versions when using a newer CLI.

When it happens

Trigger: Thrown when the GetCapabilities RPC returns a capabilities collection that does not contain BaselineCapability — the AppHost is running (and responds), but is an older build that does not advertise the required capability.

Common situations: A newer global/daily aspire CLI driving an AppHost built against an older Aspire.Hosting version; mixed-version solutions where one project's AppHost was not upgraded; pinned package versions in the AppHost that lag the CLI.

Related errors

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

Appendix: source

Thrown at src/Aspire.Cli/Backchannel/AppHostCliBackchannel.cs:357

                {
                    ActivityTracingStrategy = new ActivityTracingStrategy()
                };
                rpc.StartListening();
                activity.AddBackchannelRpcListeningEvent();

                activity.AddBackchannelGetCapabilitiesStartEvent();
                var capabilities = await rpc.InvokeWithProfilingAsync<string[]>(
                    profilingTelemetry,
                    "apphost",
                    "GetCapabilitiesAsync",
                    [],
                    cancellationToken);
                activity.SetBackchannelCapabilitySummary(capabilities, BaselineCapability);
                activity.AddBackchannelGetCapabilitiesResponseEvent();

                if (!capabilities.Any(s => s == BaselineCapability))
                {
                    throw new AppHostIncompatibleException(
                        string.Format(CultureInfo.CurrentCulture, ErrorStrings.AppHostIncompatibleWithCli, BaselineCapability),
                        BaselineCapability
                        );
                }

                rpc.Disconnected += OnRpcDisconnected;

                // Set up auto-reconnect if enabled
                if (autoReconnect)
                {
                    rpc.Disconnected += OnDisconnected;
                }
            }
            catch
            {
                rpc?.Dispose();
                throw;
            }

View on GitHub (pinned to 25830f84bd)