invoke-ai/InvokeAI · critical · MigrationError

Problem bootstrapping applied migrations: {e}

Error message

Problem bootstrapping applied migrations: {e}

What it means

Wrapper guard: any sqlite3.Error raised while bootstrapping applied migrations from legacy versions is logged, the transaction is rolled back, and re-raised as a MigrationError with the underlying message chained as the cause. It converts low-level SQLite failures into the migrator's error type.

Source

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

                    (legacy_version,),
                )
                legacy_row = cursor.fetchone()
                if legacy_row is not None and legacy_row[0] != migration_id:
                    cursor.connection.rollback()
                    raise MigrationError(
                        "Database contains inconsistent applied migration state: "
                        f"legacy version {legacy_version} is recorded for {legacy_row[0]}, expected {migration_id}"
                    )
                cursor.execute(
                    "INSERT OR IGNORE INTO applied_migrations (migration_id, legacy_version) VALUES (?, ?);",
                    (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):

View on GitHub (pinned to 0b6a024f2f)

Solutions

  1. Read the chained sqlite3 error message (the cause) to identify the root problem
  2. Ensure no other process holds the DB and file permissions allow writes
  3. Restore or repair the DB (e.g. sqlite3 .recover) if corruption is indicated
  4. Back up the DB before retrying migrations

Example fix

# before: db locked by another instance / read-only file
# after: stop other instances and ensure write access
fuser /data/invokeai/invokeai.db
chmod u+w /data/invokeai/invokeai.db
invokeai-web --root /data/invokeai
Defensive patterns

Strategy: try-catch

Validate before calling

import os, sqlite3
assert os.access(db_path, os.W_OK), f"no write access to {db_path}"
conn = sqlite3.connect(db_path)
conn.execute("PRAGMA integrity_check")
conn.execute("BEGIN IMMEDIATE; conn_rollback") if False else None

Try / catch

try:
    services.run_migrations()
except MigrationError as e:
    if "Problem bootstrapping applied migrations" in str(e):
        logger.critical("SQLite-level bootstrap failure: %s", e.__cause__)
        raise
    raise

Prevention

When it happens

Trigger: sqlite3 errors during bootstrap — locked database, disk I/O error, malformed schema (missing applied_migrations or legacy tables), permission problems on the DB file — inside _bootstrap_applied_migrations_from_legacy_versions.

Common situations: DB file locked by another running InvokeAI instance; read-only filesystem or insufficient permissions; corrupted SQLite file; schema missing expected tables.

Related errors

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