{"record":{"id":"a2dd47c94482a057","repo":"microsoft/aspire","slug":"the-dashboard-database-schema-version-formatschemaversion","errorCode":null,"errorMessage":"The dashboard database schema version {FormatSchemaVersion(existingSchemaVersion)} does not match the expected version {SchemaVersion}.","messagePattern":"The dashboard database schema version (.+?) does not match the expected version (.+?)\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"src/Aspire.Dashboard/ServiceClient/DashboardSqliteDatabase.cs","lineNumber":156,"sourceCode":"\n            using var connection = OpenConnection();\n            // Unlike synchronous, WAL journal mode is stored in the database and persists across connections\n            // and process restarts, so it only needs to be set during database initialization rather than on\n            // every open. WAL appends writes sequentially and allows readers to continue while a writer commits.\n            // See https://sqlite.org/pragma.html#pragma_journal_mode.\n            connection.Execute(\"PRAGMA journal_mode = WAL;\");\n\n            var schemaTableExists = connection.QuerySingle<long>(\"\"\"\n                SELECT COUNT(*)\n                FROM sqlite_schema\n                WHERE type = 'table' AND name = 'dashboard_schema';\n                \"\"\") != 0;\n            if (schemaTableExists)\n            {\n                var existingSchemaVersion = GetSchemaVersion(connection, transaction: null);\n                if (existingSchemaVersion != SchemaVersion)\n                {\n                    throw new InvalidOperationException($\"The dashboard database schema version {FormatSchemaVersion(existingSchemaVersion)} does not match the expected version {SchemaVersion}.\");\n                }\n            }\n\n            using var transaction = connection.BeginTransaction();\n            foreach (var script in s_schemaScripts.Value)\n            {\n                connection.Execute(script, new { SchemaVersion }, transaction);\n            }\n\n            var initializedSchemaVersion = GetSchemaVersion(connection, transaction);\n            if (initializedSchemaVersion != SchemaVersion)\n            {\n                throw new InvalidOperationException($\"The dashboard database schema was initialized to version {FormatSchemaVersion(initializedSchemaVersion)} instead of the expected version {SchemaVersion}.\");\n            }\n            transaction.Commit();\n            _schemaInitialized = true;\n        }\n    }","sourceCodeStart":138,"sourceCodeEnd":174,"githubUrl":"https://github.com/microsoft/aspire/blob/25830f84bd145686607ad00c057b3f84e2e51d43/src/Aspire.Dashboard/ServiceClient/DashboardSqliteDatabase.cs#L138-L174","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"// before: resuming against an incompatible leftover database\n// after: delete incompatible database before initializing\nif (File.Exists(dbPath))\n{\n    File.Delete(dbPath); // incompatible schema; recreate at current version\n}\nawait database.InitializeSchemaAsync();","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try\n{\n    await database.InitializeSchemaAsync();\n}\ncatch (InvalidOperationException ex) when (ex.Message.Contains(\"does not match the expected version\"))\n{\n    File.Delete(dbPath); // recreate at current schema version\n    database = new DashboardSqliteDatabase(dbPath);\n    await database.InitializeSchemaAsync();\n}","preventionTips":["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"],"tags":["dashboard","sqlite","schema-version","persistence","upgrade"],"backgroundTag":"schema-validation-failed","analyzedSha":"25830f84bd145686607ad00c057b3f84e2e51d43","analyzedAt":"2026-09-16T11:10:06.193Z","contentChangedAt":"2026-09-16T11:10:06.193Z","schemaVersion":2},"datasetVersion":"2026-09-21T04:17:39.646Z"}