microsoft/aspire · error · InvalidOperationException

BrowserMessageStrings.BrowserLogsEmptyBrowserConfiguration

Error message

BrowserMessageStrings.BrowserLogsEmptyBrowserConfiguration

What it means

When resolving the effective browser configuration for browser-logs capture, the 'browser' value must be non-empty. Resolve merges explicit values, resource-level, and global configuration; if the merged browser name is null/whitespace, the configuration cannot name a browser to launch and this InvalidOperationException is thrown using the localized resource string BrowserLogsEmptyBrowserConfiguration.

Solutions

Set a browser name in the browser-logs configuration, e.g. WithBrowser("chrome") or the equivalent config key.
Check environment variables/config sources are not overriding the browser key with an empty value.
Remove the explicit empty browser entry so the global default applies.
Inspect resolved configuration layers (explicit > resource > global) to find the layer producing the empty value.

Example fix

// before
.WithBrowserLogs(new Dictionary<string, string?> { ["browser"] = "" })

// after
.WithBrowserLogs(new Dictionary<string, string?> { ["browser"] = "chrome" })

Defensive patterns

Strategy: validation

Validate before calling

if (string.IsNullOrWhiteSpace(config["browser"]))
    throw new ArgumentException("Browser must be a non-empty name (e.g. 'chrome').");

Try / catch

try { BrowserConfiguration.Resolve(...); }
catch (InvalidOperationException ex) when (ex.Message.Contains("browser configuration"))
{ logger.LogError(ex, "Set a non-empty browser value in the browser-logs config"); throw; }

Prevention

Always set an explicit browser name when opting into browser logs.
Check env vars don't override config keys with empty strings.
Omit optional keys rather than setting them to empty.

When it happens

Trigger: Calling WithBrowserLogs / the BrowserConfiguration.Resolve path with an explicit BrowserLogs configuration where the browser key is set to an empty string, or no default browser is configured anywhere (explicit values, resource runtime config, and global runtime config all empty).

Common situations: Setting BrowserLogsBuilderExtensions.BrowserConfigurationKey to "" accidentally; clearing config via environment variables with empty values overriding defaults; forgetting to configure any browser while opting into browser logs capture.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

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

Appendix: source

Thrown at src/Aspire.Hosting.Browsers/BrowserConfiguration.cs:57

        BrowserConfiguration? resourceRuntimeConfiguration = null,
        BrowserConfiguration? globalRuntimeConfiguration = null)
    {
        ArgumentNullException.ThrowIfNull(configuration);
        ArgumentException.ThrowIfNullOrWhiteSpace(resourceName);

        var browserLogsSection = configuration.GetSection(BrowserLogsBuilderExtensions.BrowserLogsConfigurationSectionName);
        var resourceSection = browserLogsSection.GetSection(resourceName);

        // Resolution order is explicit argument -> resource-specific config -> global browser-log config -> default.
        // Resolve user-data mode before browser so the browser default can prefer Edge for shared state and Chrome for
        // disposable isolated state.
        var resolvedProfile = ResolveProfile(explicitValues, resourceRuntimeConfiguration, globalRuntimeConfiguration, resourceSection, browserLogsSection);
        var resolvedUserDataMode = ResolveUserDataMode(explicitValues, resourceRuntimeConfiguration, globalRuntimeConfiguration, resourceSection, browserLogsSection);
        var resolvedBrowser = ResolveBrowser(explicitValues, resourceRuntimeConfiguration, globalRuntimeConfiguration, resourceSection, browserLogsSection, resolvedUserDataMode);

        if (string.IsNullOrWhiteSpace(resolvedBrowser))
        {
            throw new InvalidOperationException(BrowserMessageStrings.BrowserLogsEmptyBrowserConfiguration);
        }

        if (resolvedProfile is not null && string.IsNullOrWhiteSpace(resolvedProfile))
        {
            throw new InvalidOperationException(BrowserMessageStrings.BrowserLogsEmptyProfileConfiguration);
        }

        if (resolvedUserDataMode == BrowserUserDataMode.Isolated && resolvedProfile is not null)
        {
            throw new InvalidOperationException(
                string.Format(
                    CultureInfo.CurrentCulture,
                    BrowserMessageStrings.BrowserLogsProfileRequiresSharedUserDataMode,
                    BrowserLogsBuilderExtensions.ProfileConfigurationKey,
                    resolvedProfile,
                    BrowserLogsBuilderExtensions.UserDataModeConfigurationKey,
                    BrowserUserDataMode.Isolated,
                    BrowserUserDataMode.Shared));

View on GitHub (pinned to 25830f84bd)