{"record":{"id":"1b305685897d7b40","repo":"microsoft/aspire","slug":"apphost-is-incompatible-with-the-cli-the-apphost-must-be","errorCode":null,"errorMessage":"AppHost is incompatible with the CLI. The AppHost must be updated to a version that supports the {0} capability.","messagePattern":"AppHost is incompatible with the CLI\\. The AppHost must be updated to a version that supports the (.+?) capability\\.","errorType":"exception","errorClass":"AppHostIncompatibleException","httpStatus":null,"severity":"error","filePath":"src/Aspire.Cli/Backchannel/AppHostCliBackchannel.cs","lineNumber":357,"sourceCode":"                {\n                    ActivityTracingStrategy = new ActivityTracingStrategy()\n                };\n                rpc.StartListening();\n                activity.AddBackchannelRpcListeningEvent();\n\n                activity.AddBackchannelGetCapabilitiesStartEvent();\n                var capabilities = await rpc.InvokeWithProfilingAsync<string[]>(\n                    profilingTelemetry,\n                    \"apphost\",\n                    \"GetCapabilitiesAsync\",\n                    [],\n                    cancellationToken);\n                activity.SetBackchannelCapabilitySummary(capabilities, BaselineCapability);\n                activity.AddBackchannelGetCapabilitiesResponseEvent();\n\n                if (!capabilities.Any(s => s == BaselineCapability))\n                {\n                    throw new AppHostIncompatibleException(\n                        string.Format(CultureInfo.CurrentCulture, ErrorStrings.AppHostIncompatibleWithCli, BaselineCapability),\n                        BaselineCapability\n                        );\n                }\n\n                rpc.Disconnected += OnRpcDisconnected;\n\n                // Set up auto-reconnect if enabled\n                if (autoReconnect)\n                {\n                    rpc.Disconnected += OnDisconnected;\n                }\n            }\n            catch\n            {\n                rpc?.Dispose();\n                throw;\n            }","sourceCodeStart":339,"sourceCodeEnd":375,"githubUrl":"https://github.com/microsoft/aspire/blob/25830f84bd145686607ad00c057b3f84e2e51d43/src/Aspire.Cli/Backchannel/AppHostCliBackchannel.cs#L339-L375","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\n<PackageReference Include=\"Aspire.Hosting\" Version=\"9.0.0\" />\n// after\n<PackageReference Include=\"Aspire.Hosting\" Version=\"9.5.0\" /> <!-- matches CLI baseline -->","handlingStrategy":"try-catch","validationCode":"// Before launching via CLI, check the AppHost's Aspire.Hosting version:\n// dotnet list <AppHost>.csproj package | grep Aspire.Hosting\n// ensure it is >= the CLI baseline version","typeGuard":null,"tryCatchPattern":"try\n{\n    await backchannel.ConnectAsync(socketPath, ...);\n}\ncatch (AppHostIncompatibleException ex)\n{\n    // prompt: update the AppHost's Aspire.Hosting packages to support ex capability\n}","preventionTips":["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."],"tags":["backchannel","versioning","compatibility","apphost","cli"],"backgroundTag":"version-mismatch","analyzedSha":"25830f84bd145686607ad00c057b3f84e2e51d43","analyzedAt":"2026-09-16T11:10:06.193Z","contentChangedAt":"2026-09-16T11:10:06.193Z","schemaVersion":2},"datasetVersion":"2026-09-21T04:17:39.646Z"}