Unexpected dashboard persistence mode

Error message

Unexpected dashboard persistence mode: {PersistenceMode}

What it means

DashboardRunStore's constructor switches on the configured PersistenceMode to decide how to initialize persistence (e.g. create, resume, none). The default branch throws InvalidOperationException because the mode value is outside the set of supported persistence modes.

Solutions

Set PersistenceMode to a supported value defined by the dashboard's persistence options
Validate the persisted/configured mode value with Enum.IsDefined before constructing the store
If the value comes from config parsing, fix the config source or upgrade the package so the mode is recognized

Example fix

// before
var store = new DashboardRunStore((PersistenceMode)someInt);

// after
var mode = Enum.IsDefined(typeof(PersistenceMode), someInt) ? (PersistenceMode)someInt : PersistenceMode.None;
var store = new DashboardRunStore(mode);

Defensive patterns

Strategy: validation

Validate before calling

if (!Enum.IsDefined(typeof(PersistenceMode), configuredMode))
{
    configuredMode = PersistenceMode.None; // or fail fast with a clear config error
}

Type guard

bool IsValidPersistenceMode(PersistenceMode mode) => Enum.IsDefined(typeof(PersistenceMode), mode);

Try / catch

try
{
    var store = new DashboardRunStore(mode);
}
catch (InvalidOperationException ex) when (ex.Message.Contains("Unexpected dashboard persistence mode"))
{
    // log the raw config value and fall back to a supported mode
}

Prevention

Only assign enum members defined by PersistenceMode
Validate int-to-enum casts with Enum.IsDefined
Validate config/env values before constructing the store

When it happens

Trigger: Constructing DashboardRunStore with a PersistenceMode value that is not one of the recognized enum members (an undefined enum value, or an out-of-range cast).

Common situations: A dashboard option/env configuration produced an invalid or undefined PersistenceMode; casting an int to the enum type without validation; a new mode added in a newer library version being passed to an older build.

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/3dad603a0e761efc. Report an issue: GitHub.

Appendix: source

Thrown at src/Aspire.Dashboard/ServiceClient/DashboardRunStore.cs:192

                            DatabasePath,
                            SchemaVersion);
                        DeleteDatabaseFiles(DatabasePath);
                    }
                    else
                    {
                        _logger.LogDebug("Resuming dashboard database at '{DatabasePath}'.", DatabasePath);
                    }

                    _runLock = resumeRunLock;
                }
                catch
                {
                    resumeRunLock.Dispose();
                    throw;
                }
                break;
            default:
                throw new InvalidOperationException($"Unexpected dashboard persistence mode: {PersistenceMode}");
        }

        _metadata = new DashboardRunMetadata
        {
            SchemaVersion = SchemaVersion,
            RunId = runId,
            StartedAtUtc = startedAt,
            ApplicationName = options.Value.ApplicationName,
            DatabaseFileName = Path.GetFileName(DatabasePath)
        };
        _runs = new(LoadRuns);

        _logger.LogDebug(
            "Dashboard run store initialized with persistence mode '{PersistenceMode}'. Current working directory: '{CurrentWorkingDirectory}'. Database path: '{DatabasePath}'.",
            PersistenceMode,
            CurrentWorkingDirectory,
            DatabasePath);
    }

View on GitHub (pinned to 25830f84bd)