JosefNemec/Playnite · critical · Exception

Database must be migrated before opening.

Error message

Database must be migrated before opening.

What it means

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.

Source

Thrown at source/Playnite/Database/GameDatabase.cs:543

            {
                FileSystem.CreateDirectory(DatabasePath);
                FileSystem.CreateDirectory(FilesDirectoryPath);
            }

            if (!dbExists)
            {
                Settings = new DatabaseSettings() { Version = NewFormatVersion };
            }
            else
            {
                if (Settings.Version > NewFormatVersion)
                {
                    throw new Exception($"Database version {Settings.Version} is not supported.");
                }

                if (GetMigrationRequired(DatabasePath))
                {
                    throw new Exception("Database must be migrated before opening.");
                }
            }

            LoadCollections();
            LoadUsedItems();

            // New DB setup
            if (!dbExists)
            {
                // Generate default platforms
                var platforms = Emulation.Platforms.Where(a => a.IgdbId != 0).Select(a => new Platform(a.Name) { SpecificationId = a.Id }).ToList();
                if (platforms.HasItems())
                {
                    var col = Platforms as ItemCollection<Platform>;
                    col.IsEventsEnabled = false;
                    col.Add(platforms);
                    col.IsEventsEnabled = true;
                }

View on GitHub (pinned to 5911f4e964)

Solutions

1. Run the database migration: use Playnite's built-in migration prompt or call the migration API before OpenDatabase.
2. If Playnite's startup migration didn't trigger, verify GetMigrationRequired logic and ensure the migration handler runs on startup.
3. If the migration fails, check the migration log for errors and fix the specific migration step that failed.
4. As a last resort, create a new database and re-import games from library integrations.

Example fix

// before — opening a DB that needs migration
gameDatabase.OpenDatabase(); // throws if migration required

// after — migrate first, then open
if (gameDatabase.GetMigrationRequired(dbPath))
{
    logger.Info("Database requires migration, starting migration...");
    gameDatabase.MigrateDatabase(dbPath);
}
gameDatabase.OpenDatabase();

if (gameDatabase.GetMigrationRequired(gameDatabase.DatabasePath))
{
    logger.Info("Database requires migration before opening.");
    gameDatabase.MigrateDatabase(gameDatabase.DatabasePath);
    if (gameDatabase.GetMigrationRequired(gameDatabase.DatabasePath))
        throw new InvalidOperationException("Migration did not complete successfully.");
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Database version {Settings.Version} is not supported.
• Database path cannot be empty.
• Cannot add file to database, file not found.
• Emulator not found.
• {property.GetType()} property type is not supported in this

AI-assisted analysis of JosefNemec/Playnite@5911f4e964 (2026-08-13). Data as JSON: /api/errors/3ca8e8e264fa241e. Report an issue: GitHub.