microsoft/aspire · error · InvalidOperationException

BrowserMessageStrings.BrowserLogsInvalidUserDataModeConfigur…

Error message

BrowserMessageStrings.BrowserLogsInvalidUserDataModeConfiguration

What it means

ParseUserDataMode converts a configuration string into the BrowserUserDataMode enum using a case-insensitive Enum.TryParse. When the value is present but not one of the valid mode names, this error is thrown with the localized string BrowserLogsInvalidUserDataModeConfiguration, echoing the bad value and the valid alternatives (e.g. Shared). It protects against silent fallback to an unintended mode.

Solutions

Set the value to a valid BrowserUserDataMode name exactly as documented, e.g. 'Shared' or 'Isolated' (case-insensitive).
Echo the accepted values from the error message — it lists the valid alternatives.
Validate/normalize the value at the config source (e.g. in CI or templating) before it reaches the app host.
Search configuration layers for stale keys from a renamed enum value in a newer package version.

Example fix

// before
["userdatamode"] = "sandboxed" // invalid

// after
["userdatamode"] = "Isolated"

Defensive patterns

Strategy: validation

Validate before calling

var mode = config["userdatamode"];
if (mode is { } && !Enum.TryParse<BrowserUserDataMode>(mode, ignoreCase: true, out _))
    throw new ArgumentException($"userdatamode '{mode}' is invalid; use Shared or Isolated.");

Try / catch

try { BrowserConfiguration.Resolve(...); }
catch (InvalidOperationException ex) when (ex.Message.Contains("user data mode"))
{ logger.LogError(ex, "Invalid userdatamode value; expected Shared or Isolated"); throw; }

Prevention

Only use documented enum names ('Shared', 'Isolated') in config.
Validate values at the config source in CI or templating.
Beware of renaming enum values across package upgrades — grep configs on upgrade.

When it happens

Trigger: Setting the UserDataModeConfigurationKey configuration entry (explicit dict, resource config, or env var) to anything other than a valid BrowserUserDataMode name, e.g. "userdatamode" = "sandboxed", "temp", or "1".

Common situations: Typos like 'isolatte' or 'shared-mode'; casing assumptions after switching to case-sensitive custom parsing elsewhere; translating config values between tools that use different vocabularies; passing numeric enum values as strings.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

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

Appendix: source

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

            return "msedge";
        }

        return "chrome";
    }

    private static ConfigurationValue<BrowserUserDataMode> ParseUserDataMode(string? value)
    {
        if (string.IsNullOrWhiteSpace(value))
        {
            return ConfigurationValue<BrowserUserDataMode>.Missing;
        }

        if (Enum.TryParse<BrowserUserDataMode>(value, ignoreCase: true, out var parsed))
        {
            return ConfigurationValue<BrowserUserDataMode>.Present(parsed);
        }

        throw new InvalidOperationException(
            string.Format(
                CultureInfo.CurrentCulture,
                BrowserMessageStrings.BrowserLogsInvalidUserDataModeConfiguration,
                value,
                BrowserLogsBuilderExtensions.UserDataModeConfigurationKey,
                BrowserUserDataMode.Shared,
                BrowserUserDataMode.Isolated));
    }

    private static string GetDefaultBrowser(BrowserUserDataMode userDataMode) =>
        GetDefaultBrowser(userDataMode, ChromiumBrowserResolver.TryResolveExecutable);

    private static string? ResolveProfile(
        BrowserConfigurationExplicitValues explicitValues,
        BrowserConfiguration? resourceRuntimeConfiguration,
        BrowserConfiguration? globalRuntimeConfiguration,
        IConfigurationSection resourceSection,
        IConfigurationSection browserLogsSection)

View on GitHub (pinned to 25830f84bd)