invoke-ai/InvokeAI · critical · MigrationError

Database contains unknown applied migration IDs: {unknown_id

Error message

Database contains unknown applied migration IDs: {unknown_ids}

What it means

get_migration_plan builds a deterministic migration plan from the set of applied migration IDs recorded in the database. If the DB records migration IDs that are not registered in the current MigrationSet (e.g. after a downgrade or use of a different build), the mismatch is unrecoverable and a MigrationError is raised listing the unknown IDs.

Source

Thrown at invokeai/app/services/shared/sqlite_migrator/sqlite_migrator_common.py:237

            if migration_id in visiting:
                raise MigrationError("Migration dependency graph contains a cycle")
            visiting.add(migration_id)
            if migration.depends_on is not None:
                visit(migrations_by_id[migration.depends_on])
            visiting.remove(migration_id)
            visited.add(migration_id)

        for migration in self._migrations:
            visit(migration)

    def get_migration_plan(self, applied_migration_ids: set[str]) -> list[Migration]:
        """Gets a deterministic migration plan from the set of applied migration IDs."""
        self.validate_dependency_graph()
        known_migration_ids = set(self.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}")

        plan: list[Migration] = []
        planned_or_applied_ids = set(applied_migration_ids)
        remaining = {
            migration.id: migration for migration in self._migrations if migration.id not in applied_migration_ids
        }

        while remaining:
            runnable = sorted(
                (
                    migration
                    for migration in remaining.values()
                    if migration.depends_on is None or migration.depends_on in planned_or_applied_ids
                ),
                key=lambda migration: migration.sort_key,
            )
            if not runnable:
                raise MigrationError("Migration dependency graph cannot be resolved")

View on GitHub (pinned to 0b6a024f2f)

Solutions

Restore a database backup taken at the version you are running
Upgrade InvokeAI to a version that includes the unknown migration IDs
Start from a fresh database if the data is disposable
Manually inspect/remove the unknown rows in applied_migrations (last resort)

Example fix

# before: launch after downgrade
invokeai-web --root /data/invokeai
# after: upgrade to the build that knows those migrations
pip install -U invokeai && invokeai-web --root /data/invokeai

Defensive patterns

Strategy: validation

Validate before calling

# before launching, inspect applied migrations vs the build
import sqlite3
conn = sqlite3.connect(db_path)
applied = {r[0] for r in conn.execute("SELECT migration_id FROM applied_migrations")}
# known ids come from the build's migration set
unknown = applied - known_migration_ids
assert not unknown, f"downgrade detected; unknown migrations: {unknown}"

Try / catch

try:
    services.run_migrations()
except MigrationError as e:
    if "unknown applied migration IDs" in str(e):
        logger.critical("DB from a newer InvokeAI version: %s", e)
        raise
    raise

Prevention

Back up the DB before upgrading or downgrading InvokeAI
Never point an older build at a DB migrated by a newer build
Pin InvokeAI versions in deployment environments

When it happens

Trigger: Running migrations against a database whose applied_migrations table contains IDs absent from self.migrations_by_id — typically after downgrading InvokeAI or pointing the app at a DB from a newer/older version with different migrations.

Common situations: Downgrading InvokeAI then launching against the same DB; switching branches/builds with different migration registries; corrupted or hand-edited applied_migrations rows.

Related errors

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