invoke-ai/InvokeAI · error · MigrationError

Database contains unknown applied migration IDs: {unknown_id

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.

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)

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.