invoke-ai/InvokeAI · error · MigrationError

Database contains inconsistent applied migration state: {mig

Error message

Database contains inconsistent applied migration state: {migration_id} is recorded with legacy version {legacy_version}, expected {migration.to_version}

What it means

A migration recorded in applied_migrations carries a legacy_version that does not match the to_version declared by its registered Migration. The two migration bookkeeping stores disagree, so the migrator halts to avoid applying migrations on top of inconsistent state.

Source

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

                raise MigrationError(f"Database contains unknown legacy migration version: {legacy_version}")

    def _validate_existing_applied_legacy_migrations(self, cursor: sqlite3.Cursor) -> None:
        """Validates applied IDs for legacy migrations against legacy numeric rows."""
        registered_migrations = self._migration_set.migrations_by_id
        cursor.execute("SELECT migration_id, legacy_version FROM applied_migrations;")
        applied_rows = cursor.fetchall()

        cursor.execute("SELECT version FROM migrations WHERE version > 0;")
        legacy_versions = {row[0] for row in cursor.fetchall()}

        for row in applied_rows:
            migration_id = row[0]
            legacy_version = row[1]
            migration = registered_migrations[migration_id]
            if migration.to_version is None:
                continue
            if legacy_version != migration.to_version:
                raise MigrationError(
                    "Database contains inconsistent applied migration state: "
                    f"{migration_id} is recorded with legacy version {legacy_version}, "
                    f"expected {migration.to_version}"
                )
            if legacy_version not in legacy_versions:
                raise MigrationError(
                    "Database contains inconsistent applied migration state: "
                    f"{migration_id} is applied, but legacy version {legacy_version} is missing"
                )

    def _needs_applied_migrations_bootstrap(self, cursor: sqlite3.Cursor) -> bool:
        """Checks whether legacy numeric rows need to be written to applied_migrations."""
        cursor.execute("SELECT version FROM migrations WHERE version > 0;")
        legacy_versions = {row[0] for row in cursor.fetchall()}
        if len(legacy_versions) == 0:
            return False

        cursor.execute("SELECT name FROM sqlite_master WHERE type='table' AND name='applied_migrations';")

View on GitHub (pinned to 0b6a024f2f)

Solutions

Restore the database from a backup taken before the corruption.
Correct the mismatched legacy_version value in applied_migrations to match the expected to_version, after verifying the actual schema state.
Delete both stores and re-initialize the database if it is disposable (e.g. regenerate the DB and re-import models).

Example fix

// before: hand-edited row disagrees
-- applied_migrations: ('migration_4', 3)
// after: align with the migration's declared to_version
UPDATE applied_migrations SET legacy_version = 4 WHERE migration_id = 'migration_4';

Defensive patterns

Strategy: validation

Validate before calling

import sqlite3
conn = sqlite3.connect(db_path)
rows = conn.execute(
    "SELECT migration_id, legacy_version FROM applied_migrations WHERE legacy_version IS NOT NULL"
).fetchall()
for mid, lv in rows:
    print(mid, lv)  # cross-check each against the migration's declared to_version before launching

Try / catch

try:
    migrator.run_migrations()
except MigrationError as e:
    if "inconsistent applied migration state" in str(e):
        # restore from backup rather than patching live
        raise SystemExit(f"Restore DB from backup: {e}")
    raise

Prevention

Never hand-edit the migrations or applied_migrations tables.
Take a DB backup before any manual schema intervention.
Avoid killing the process during a migration run.
Copy the whole DB file, never individual tables, when moving installs.

When it happens

Trigger: run_migrations() -> _validate_existing_applied_legacy_migrations: for an applied row, migration.to_version is not None and legacy_version != migration.to_version.

Common situations: The applied_migrations or migrations table was hand-edited; a partially failed/aborted migration run left rows partially updated; the DB was copied mid-migration or modified by a different app version.

Related errors

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