microsoft/aspire · error · ExtensionIncompatibleException

Aspire Extension is incompatible with the CLI. The…

Error message

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

What it means

During ConnectAsync the CLI calls the extension's 'getCapabilities' RPC (passing the auth token). If the returned capability list does not include the 'Baseline' capability, the extension is too old to work with this CLI, and an ExtensionIncompatibleException is thrown telling the user to update the extension to a version supporting the Baseline capability.

Solutions

Update the Aspire VS Code extension to the latest version in VS Code (Extensions panel → Update / Reload).
Verify the extension and CLI versions align (aspire --version vs. the installed extension version) and update the CLI if it is intentionally older.
Fully reload/restart VS Code after updating so the extension process (and its backchannel endpoint) is replaced.

Defensive patterns

Strategy: try-catch

Try / catch

try { await backchannel.ConnectAsync(endpoint, ct); }
catch (ExtensionIncompatibleException ex)
{ Console.Error.WriteLine($"Update the Aspire VS Code extension: {ex.Message}"); }

Prevention

Keep the Aspire CLI and VS Code extension versions in sync; update both together.
Check the extension's reported capabilities/version before connecting when possible.
Reload VS Code after CLI upgrades so the extension process is fresh.

When it happens

Trigger: Connecting to an Aspire VS Code extension whose getCapabilities response lacks KnownCapabilities.Baseline — i.e., an outdated extension matched with a newer CLI.

Common situations: User upgraded the Aspire CLI (dotnet tool update / new daily channel) but the VS Code extension remained on an older release, or a pinned/stale extension build is cached in VS Code.

Related errors

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

Appendix: source

Thrown at src/Aspire.Cli/Backchannel/ExtensionBackchannel.cs:312

                static void AddLocalRpcTarget(JsonRpc rpc, IExtensionRpcTarget target)
                {
                    // We don't want to notify the client of events because we are not using the
                    // event system in the extension.
                    rpc.AddLocalRpcTarget(target, new JsonRpcTargetOptions() { NotifyClientOfEvents = false });
                }

                var rpc = new JsonRpc(new HeaderDelimitedMessageHandler(stream, stream, BackchannelJsonSerializerContext.CreateRpcMessageFormatter()));
                AddLocalRpcTarget(rpc, _target);
                rpc.StartListening();

                var capabilities = await rpc.InvokeWithCancellationAsync<string[]>(
                    "getCapabilities",
                    [_token],
                    cancellationToken);

                if (!capabilities.Any(s => s == KnownCapabilities.Baseline))
                {
                    throw new ExtensionIncompatibleException(
                        string.Format(CultureInfo.CurrentCulture, ErrorStrings.ExtensionIncompatibleWithCli,
                            KnownCapabilities.Baseline),
                        KnownCapabilities.Baseline
                    );
                }

                _rpcTaskCompletionSource.SetResult(rpc);
            }
            catch (RemoteMethodNotFoundException ex)
            {
                _logger.LogError(ex,
                    "Failed to connect to {Name} backchannel. The connection must be updated to a version that supports the {BaselineCapability} capability.",
                    Name,
                    KnownCapabilities.Baseline);

                throw new ExtensionIncompatibleException(
                    string.Format(CultureInfo.CurrentCulture, ErrorStrings.ExtensionIncompatibleWithCli,
                        KnownCapabilities.Baseline),

View on GitHub (pinned to 25830f84bd)