invoke-ai/InvokeAI · error · MigrationError

Database contains unknown applied migration IDs

Error message

Database contains unknown applied migration IDs: {unknown_ids}

What it means

The SQLite migrator found migration IDs recorded in the database's applied_migrations table that are not registered in the MigrationSet the app was built with. This means the database was created or modified by a different (usually newer) version of the application than the one currently running. It aborts startup rather than silently running migrations over unknown state.

Solutions

Upgrade the application back to the version that created those migrations (matching or newer than the DB).
Restore the database from a backup taken before the newer version ran.
If the downgrade is intentional and safe, manually delete the unknown rows from applied_migrations only after confirming the schema changes are compatible (risk: data/schema corruption).

Example fix

// before: running InvokeAI 5.x against a DB migrated by 6.x
# pip install invokeai==5.3.0
// after: install the version matching the DB
# pip install invokeai==6.0.1
# invokeai-configure --version  # then restart; run_migrations() passes validation

Defensive patterns

Strategy: try-catch

Validate before calling

// before launching the app / running migrations
import sqlite3
conn = sqlite3.connect(db_path)
applied = {r[0] for r in conn.execute("SELECT migration_id FROM applied_migrations")}
print(sorted(applied))  # compare against the MigrationSet of your app version;
                        # if IDs look newer than your install, upgrade first

Try / catch

from invokeai.app.services.shared.sqlite_migrator.sqlite_migrator_common import MigrationError
try:
    migrator.run_migrations()
except MigrationError as e:
    if "unknown applied migration IDs" in str(e):
        # stop and upgrade the app or restore a backup; do not auto-retry
        raise SystemExit(f"DB was migrated by a newer version: {e}")
    raise

Prevention

Always back up the SQLite database before upgrading InvokeAI.
Never run an older app version against a DB migrated by a newer one.
Avoid sharing one database file across multiple app versions/installs.
Check release notes for schema migrations before downgrading.

When it happens

Trigger: Calling run_migrations() when the DB's applied_migrations table contains migration IDs absent from self._migration_set.migrations_by_id (unknown_applied_ids non-empty after set subtraction).

Common situations: User downgraded InvokeAI to an older release after a newer version migrated the DB; running two different app versions against the same database file; a custom/branch build added migrations then the user switched to stock.

Related errors

AI-assisted analysis of invoke-ai/InvokeAI@0b6a024f2f (2026-08-29). Data as JSON: /api/errors/b5ead3c67486e395. Report an issue: GitHub.

Appendix: source

Thrown at invokeai/app/services/shared/sqlite_migrator/sqlite_migrator_impl.py:219

                    (migration_id, legacy_version),
                )
            cursor.connection.commit()
        except sqlite3.Error as e:
            msg = f"Problem bootstrapping applied migrations: {e}"
            self._logger.error(msg)
            cursor.connection.rollback()
            raise MigrationError(msg) from e

    def _validate_existing_applied_migrations(self, cursor: sqlite3.Cursor) -> None:
        """Validates existing applied migration IDs before creating or mutating migrator metadata."""
        applied_migration_ids = self._get_applied_migration_ids(cursor=cursor)
        if len(applied_migration_ids) == 0:
            return
        known_migration_ids = set(self._migration_set.migrations_by_id)
        unknown_applied_ids = applied_migration_ids - known_migration_ids
        if unknown_applied_ids:
            unknown_ids = ", ".join(sorted(unknown_applied_ids))
            raise MigrationError(f"Database contains unknown applied migration IDs: {unknown_ids}")

    def _validate_existing_legacy_migrations(self, cursor: sqlite3.Cursor) -> None:
        """Validates existing legacy migration versions before creating applied migration metadata."""
        try:
            cursor.execute("SELECT version FROM migrations WHERE version > 0 ORDER BY version;")
        except sqlite3.OperationalError as e:
            if "no such table" in str(e):
                return
            raise

        registered_migration_ids = self._migration_set.migrations_by_id
        for row in cursor.fetchall():
            legacy_version = row[0]
            migration_id = f"migration_{legacy_version}"
            if migration_id not in registered_migration_ids:
                raise MigrationError(f"Database contains unknown legacy migration version: {legacy_version}")

    def _validate_existing_applied_legacy_migrations(self, cursor: sqlite3.Cursor) -> None:

View on GitHub (pinned to 0b6a024f2f)