microsoft/aspire · error · InvalidOperationException

Cannot resolve the isolated browser user data directory…

Error message

Cannot resolve the isolated browser user data directory because the AppHost path identifier is not available. Use '{0}' user data mode or run from a configured AppHost.

What it means

BrowserUserDataPathResolver.GetAppHostSegment throws this when BrowserConfiguration.AppHostKey is null/whitespace while resolving an 'Isolated' user-data directory. The isolated path layout embeds a hash/segment derived from the AppHost identity, so without an AppHostKey the resolver cannot construct a unique per-AppHost directory and refuses to guess a shared location.

Solutions

Set configuration.AppHostKey to the AppHost's identifier before resolving the user data path.
Use BrowserUserDataMode with a non-isolated mode (per the message) that does not require the AppHost segment.
Run the browser launch from a properly configured AppHost so the key is populated automatically.
Fall back to a non-isolated data directory when AppHostKey is unavailable.

Example fix

// before
var config = new BrowserConfiguration { UserDataMode = BrowserUserDataMode.Isolated };
var path = BrowserUserDataPathResolver.Resolve(config);
// after
var config = new BrowserConfiguration { UserDataMode = BrowserUserDataMode.Isolated, AppHostKey = appHostIdentifier };
var path = BrowserUserDataPathResolver.Resolve(config);

Defensive patterns

Strategy: validation

Validate before calling

if (string.IsNullOrWhiteSpace(config.AppHostKey) && config.UserDataMode == BrowserUserDataMode.Isolated)
{
    config = config with { UserDataMode = BrowserUserDataMode.Default };
}

Try / catch

try
{
    var path = BrowserUserDataPathResolver.Resolve(config);
}
catch (InvalidOperationException ex) when (ex.Message.Contains("user data directory"))
{
    config = config with { UserDataMode = BrowserUserDataMode.Default };
    var path = BrowserUserDataPathResolver.Resolve(config);
}

Prevention

Always populate AppHostKey when constructing BrowserConfiguration in non-AppHost contexts.
Pick the user data mode once, based on whether an AppHost identity is available.
Add a startup assertion that required configuration fields are set.

When it happens

Trigger: Using BrowserUserDataMode.Isolated (the message interpolates the Isolated mode name) while the BrowserConfiguration was built without setting AppHostKey — e.g., running outside a configured AppHost context.

Common situations: Launching a tracked browser from a standalone tool or test host that has no AppHost; constructing BrowserConfiguration manually and forgetting AppHostKey; switching user data mode to Isolated without migrating configuration.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

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

Appendix: source

Thrown at src/Aspire.Hosting.Browsers/BrowserUserDataPathResolver.cs:105

                "Application Support",
                "Aspire",
                "BrowserData");
        }

        // XDG: prefer XDG_DATA_HOME, fall back to ~/.local/share. Lower-case segment names match the
        // conventional XDG layout (e.g. ~/.config/google-chrome).
        var xdgDataHome = Environment.GetEnvironmentVariable("XDG_DATA_HOME");
        var dataHome = !string.IsNullOrEmpty(xdgDataHome)
            ? xdgDataHome
            : Path.Combine(Environment.GetFolderPath(Environment.SpecialFolder.UserProfile), ".local", "share");
        return Path.Combine(dataHome, "aspire", "browser-data");
    }

    private static string GetAppHostSegment(BrowserConfiguration configuration)
    {
        if (string.IsNullOrWhiteSpace(configuration.AppHostKey))
        {
            throw new InvalidOperationException(
                string.Format(
                    CultureInfo.CurrentCulture,
                    BrowserMessageStrings.BrowserLogsAppHostPathShaNotAvailable,
                    BrowserUserDataMode.Isolated));
        }

        return configuration.AppHostKey.Length > AppHostShaSegmentLength
            ? configuration.AppHostKey[..AppHostShaSegmentLength]
            : configuration.AppHostKey;
    }

    // Maps a logical browser name or executable path to a stable lower-case folder segment so a Chrome -> Edge
    // configuration flip never silently shares state with the previous browser. Unknown executables fall back to
    // a sanitized form of the file name without extension.
    private static string NormalizeBrowserSegment(string browser)
    {
        var name = Path.IsPathRooted(browser) || Path.IsPathFullyQualified(browser)
            ? Path.GetFileNameWithoutExtension(browser)

View on GitHub (pinned to 25830f84bd)