{"record":{"id":"3ca8e8e264fa241e","repo":"JosefNemec/Playnite","slug":"database-must-be-migrated-before-opening","errorCode":null,"errorMessage":"Database must be migrated before opening.","messagePattern":"Database must be migrated before opening\\.","errorType":"exception","errorClass":"Exception","httpStatus":null,"severity":"critical","filePath":"source/Playnite/Database/GameDatabase.cs","lineNumber":543,"sourceCode":"            {\r\n                FileSystem.CreateDirectory(DatabasePath);\r\n                FileSystem.CreateDirectory(FilesDirectoryPath);\r\n            }\r\n\r\n            if (!dbExists)\r\n            {\r\n                Settings = new DatabaseSettings() { Version = NewFormatVersion };\r\n            }\r\n            else\r\n            {\r\n                if (Settings.Version > NewFormatVersion)\r\n                {\r\n                    throw new Exception($\"Database version {Settings.Version} is not supported.\");\r\n                }\r\n\r\n                if (GetMigrationRequired(DatabasePath))\r\n                {\r\n                    throw new Exception(\"Database must be migrated before opening.\");\r\n                }\r\n            }\r\n\r\n            LoadCollections();\r\n            LoadUsedItems();\r\n\r\n            // New DB setup\r\n            if (!dbExists)\r\n            {\r\n                // Generate default platforms\r\n                var platforms = Emulation.Platforms.Where(a => a.IgdbId != 0).Select(a => new Platform(a.Name) { SpecificationId = a.Id }).ToList();\r\n                if (platforms.HasItems())\r\n                {\r\n                    var col = Platforms as ItemCollection<Platform>;\r\n                    col.IsEventsEnabled = false;\r\n                    col.Add(platforms);\r\n                    col.IsEventsEnabled = true;\r\n                }\r","sourceCodeStart":525,"sourceCodeEnd":561,"githubUrl":"https://github.com/JosefNemec/Playnite/blob/5911f4e964e628aa7a69c2030ab35101afa63067/source/Playnite/Database/GameDatabase.cs#L525-L561","documentation":"Thrown as a generic Exception by GameDatabase.OpenDatabase() when GetMigrationRequired(DatabasePath) returns true, indicating the existing database uses an older format that must be migrated before it can be opened. Playnite refuses to open an unmigrated database to avoid reading stale or incompatible data structures.","triggerScenarios":"The database was created by an older Playnite version whose on-disk format differs from the current NewFormatVersion. GetMigrationRequired detects markers (old file structures, version flags) that indicate the data needs transformation. OpenDatabase is called directly without running the migration step first.","commonSituations":"Upgrading Playnite across a major version boundary that changed the database format. Copying a database from an older Playnite install to a newer one without running migration. A previous migration attempt failed or was interrupted, leaving the DB in a pre-migration state. A portable install where the migration step was skipped.","solutions":["Run the database migration: use Playnite's built-in migration prompt or call the migration API before OpenDatabase.","If Playnite's startup migration didn't trigger, verify GetMigrationRequired logic and ensure the migration handler runs on startup.","If the migration fails, check the migration log for errors and fix the specific migration step that failed.","As a last resort, create a new database and re-import games from library integrations."],"exampleFix":"// before — opening a DB that needs migration\ngameDatabase.OpenDatabase(); // throws if migration required\n\n// after — migrate first, then open\nif (gameDatabase.GetMigrationRequired(dbPath))\n{\n    logger.Info(\"Database requires migration, starting migration...\");\n    gameDatabase.MigrateDatabase(dbPath);\n}\ngameDatabase.OpenDatabase();","handlingStrategy":"validation","validationCode":"if (gameDatabase.GetMigrationRequired(gameDatabase.DatabasePath))\n{\n    logger.Info(\"Database requires migration before opening.\");\n    gameDatabase.MigrateDatabase(gameDatabase.DatabasePath);\n    if (gameDatabase.GetMigrationRequired(gameDatabase.DatabasePath))\n        throw new InvalidOperationException(\"Migration did not complete successfully.\");\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always run migration checks during startup before OpenDatabase.","Back up the database before migration.","Log migration steps and handle failures with clear error messages.","Test migration on a copy when upgrading across major versions."],"tags":["database","migration","version-upgrade","schema","game-database"],"backgroundTag":null,"analyzedSha":"5911f4e964e628aa7a69c2030ab35101afa63067","analyzedAt":"2026-08-13T17:38:25.713Z","schemaVersion":2},"datasetVersion":"2026-08-13T19:17:28.613Z"}