microsoft/aspire · error · InvalidOperationException

This version of the Aspire extension does not support…

Error message

This version of the Aspire extension does not support browser debugging. Please update the Aspire extension to use browser debugging support with WithBrowserDebugger().

What it means

Browser debugging for JavaScript resources is implemented via the Aspire VS Code extension, which advertises its capabilities (SupportedLaunchConfigurations) in a DEBUG_SESSION_INFO payload. If the extension's declared capabilities do not include the browser-launch capability, the app host throws this error because the connected extension is too old to accept the launch configuration.

Solutions

  1. Update the Aspire VS Code extension to the latest version and restart the debugging session.
  2. If you cannot update, remove .WithBrowserDebugger() from the resource and launch the browser manually using the dashboard endpoint URL.
  3. Verify the DEBUG_SESSION_INFO JSON contains the browser capability in SupportedLaunchConfigurations before calling WithBrowserDebugger().

Example fix

// before (old extension installed)
var app = builder.AddNpmApp("frontend", "./frontend")
    .WithBrowserDebugger();
// after
var app = builder.AddNpmApp("frontend", "./frontend"); // update extension, then re-add:
// .WithBrowserDebugger();
Defensive patterns

Strategy: validation

Validate before calling

var infoJson = configuration["DEBUG_SESSION_INFO"];
var supportsBrowser = infoJson is not null &&
    JsonSerializer.Deserialize<JsonElement>(infoJson)
        .TryGetProperty("supportedLaunchConfigurations", out var cfg) &&
    cfg.EnumerateArray().Any(c => c.GetString() == "browser");
if (!supportsBrowser) { /* skip WithBrowserDebugger or prompt extension update */ }

Try / catch

try { app.WithBrowserDebugger(); } catch (InvalidOperationException ex) when (ex.Message.Contains("does not support browser debugging")) { /* fall back to manual browser launch */ }

Prevention

When it happens

Trigger: Running an AppHost whose JavaScript resource uses WithBrowserDebugger() while the installed Aspire VS Code extension version lacks the browser-debugging launch capability (SupportedLaunchConfigurations missing the BrowserCapability string).

Common situations: Working on a machine with an outdated Aspire VS Code extension while using a recent Aspire.Hosting SDK; CI or a teammate's environment with an older extension; DEBUG_SESSION_INFO containing valid JSON but an old capability list.

Understand the failure class

Background: "is not a compatible type" / "cannot merge" errors: when a value's type doesn't match what the library requires — this error's family across 65 libraries.

Related errors

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

Appendix: source

Thrown at src/Aspire.Hosting.JavaScript/JavaScriptHostingExtensions.cs:2993

                    };
                },
                BrowserCapability);

        return builder;
    }

    private static void ValidateBrowserCapability<T>(IResourceBuilder<T> builder) where T : IResource
    {
        var configuration = builder.ApplicationBuilder.Configuration;

        try
        {
            if (configuration["DEBUG_SESSION_INFO"] is { } debugSessionInfoJson
                && JsonSerializer.Deserialize<DebugSessionCapabilities>(debugSessionInfoJson) is { } info
                && info.SupportedLaunchConfigurations is not null
                && !info.SupportedLaunchConfigurations.Contains(BrowserCapability))
            {
                throw new InvalidOperationException(
                    "This version of the Aspire extension does not support browser debugging. Please update the Aspire extension to use browser debugging support with WithBrowserDebugger().");
            }
        }
        catch (JsonException)
        {
            // If we can't parse the debug session info, skip validation
        }
    }

    private sealed class DebugSessionCapabilities
    {
        [JsonPropertyName("supported_launch_configurations")]
        public string[]? SupportedLaunchConfigurations { get; set; }
    }

    private static void AddInstaller<TResource>(IResourceBuilder<TResource> resource, bool install) where TResource : JavaScriptAppResource
    {
        // Only install packages if in run mode

View on GitHub (pinned to 25830f84bd)