The dashboard database schema version

Error message

The dashboard database schema version {FormatSchemaVersion(existingSchemaVersion)} does not match the expected version {SchemaVersion}.

What it means

DashboardSqliteDatabase.InitializeSchemaAsync checks whether an existing database already has a schema table, and if so compares its stored schema version to the expected SchemaVersion. It throws InvalidOperationException when the database on disk was created with a different dashboard schema version, refusing to run migration scripts against an incompatible database.

Solutions

Delete the existing database file so the schema is created fresh at the current version
Resume with the matching dashboard version that created the database, or let the store recreate it
Check GetSchemaVersion/the schema table to confirm the on-disk version, then migrate or discard accordingly

Example fix

// before: resuming against an incompatible leftover database
// after: delete incompatible database before initializing
if (File.Exists(dbPath))
{
    File.Delete(dbPath); // incompatible schema; recreate at current version
}
await database.InitializeSchemaAsync();

Defensive patterns

Strategy: try-catch

Try / catch

try
{
    await database.InitializeSchemaAsync();
}
catch (InvalidOperationException ex) when (ex.Message.Contains("does not match the expected version"))
{
    File.Delete(dbPath); // recreate at current schema version
    database = new DashboardSqliteDatabase(dbPath);
    await database.InitializeSchemaAsync();
}

Prevention

Delete leftover database files when upgrading dashboard versions
Match the dashboard version to the version that created the database when resuming
Keep one dashboard version per database path

When it happens

Trigger: Opening/initializing a SQLite database file that already exists with an older or newer schema version than the current DashboardSqliteDatabase.SchemaVersion — e.g. ResumeMode reusing an application database from a previous version.

Common situations: Upgrading Aspire and resuming a run/application whose database was created by a prior dashboard version; a leftover database file from a previous install; opening an unrelated SQLite file at the configured database path.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

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

Appendix: source

Thrown at src/Aspire.Dashboard/ServiceClient/DashboardSqliteDatabase.cs:156

            using var connection = OpenConnection();
            // Unlike synchronous, WAL journal mode is stored in the database and persists across connections
            // and process restarts, so it only needs to be set during database initialization rather than on
            // every open. WAL appends writes sequentially and allows readers to continue while a writer commits.
            // See https://sqlite.org/pragma.html#pragma_journal_mode.
            connection.Execute("PRAGMA journal_mode = WAL;");

            var schemaTableExists = connection.QuerySingle<long>("""
                SELECT COUNT(*)
                FROM sqlite_schema
                WHERE type = 'table' AND name = 'dashboard_schema';
                """) != 0;
            if (schemaTableExists)
            {
                var existingSchemaVersion = GetSchemaVersion(connection, transaction: null);
                if (existingSchemaVersion != SchemaVersion)
                {
                    throw new InvalidOperationException($"The dashboard database schema version {FormatSchemaVersion(existingSchemaVersion)} does not match the expected version {SchemaVersion}.");
                }
            }

            using var transaction = connection.BeginTransaction();
            foreach (var script in s_schemaScripts.Value)
            {
                connection.Execute(script, new { SchemaVersion }, transaction);
            }

            var initializedSchemaVersion = GetSchemaVersion(connection, transaction);
            if (initializedSchemaVersion != SchemaVersion)
            {
                throw new InvalidOperationException($"The dashboard database schema was initialized to version {FormatSchemaVersion(initializedSchemaVersion)} instead of the expected version {SchemaVersion}.");
            }
            transaction.Commit();
            _schemaInitialized = true;
        }
    }

View on GitHub (pinned to 25830f84bd)