{"record":{"id":"2230490ccc2a9ac3","repo":"invoke-ai/InvokeAI","slug":"database-contains-unknown-legacy-migration-version","errorCode":null,"errorMessage":"Database contains unknown legacy migration version: {legacy_version}","messagePattern":"Database contains unknown legacy migration version: (.+?)","errorType":"exception","errorClass":"MigrationError","httpStatus":null,"severity":"critical","filePath":"invokeai/app/services/shared/sqlite_migrator/sqlite_migrator_impl.py","lineNumber":175,"sourceCode":"                \"\"\"\n            )\n        except sqlite3.Error as e:\n            msg = f\"Problem creating applied_migrations table: {e}\"\n            self._logger.error(msg)\n            cursor.connection.rollback()\n            raise MigrationError(msg) from e\n\n    def _bootstrap_applied_migrations_from_legacy_versions(self, cursor: sqlite3.Cursor) -> None:\n        \"\"\"Backfills applied migration IDs from legacy numeric migration rows.\"\"\"\n        try:\n            cursor.execute(\"SELECT version FROM migrations WHERE version > 0 ORDER BY version;\")\n            legacy_versions = [row[0] for row in cursor.fetchall()]\n            registered_migration_ids = self._migration_set.migrations_by_id\n            for legacy_version in legacy_versions:\n                migration_id = f\"migration_{legacy_version}\"\n                if migration_id not in registered_migration_ids:\n                    cursor.connection.rollback()\n                    raise MigrationError(f\"Database contains unknown legacy migration version: {legacy_version}\")\n                cursor.execute(\n                    \"SELECT legacy_version FROM applied_migrations WHERE migration_id = ?;\",\n                    (migration_id,),\n                )\n                migration_row = cursor.fetchone()\n                if migration_row is not None and migration_row[0] != legacy_version:\n                    cursor.connection.rollback()\n                    raise MigrationError(\n                        \"Database contains inconsistent applied migration state: \"\n                        f\"{migration_id} is recorded with legacy version {migration_row[0]}, \"\n                        f\"expected {legacy_version}\"\n                    )\n                cursor.execute(\n                    \"SELECT migration_id FROM applied_migrations WHERE legacy_version = ?;\",\n                    (legacy_version,),\n                )\n                legacy_row = cursor.fetchone()\n                if legacy_row is not None and legacy_row[0] != migration_id:","sourceCodeStart":157,"sourceCodeEnd":193,"githubUrl":"https://github.com/invoke-ai/InvokeAI/blob/0b6a024f2ff6a86bfb953dcdb9cc504ef7397a06/invokeai/app/services/shared/sqlite_migrator/sqlite_migrator_impl.py#L157-L193","documentation":"When bootstrapping the modern applied_migrations table from the legacy migration-version scheme, each legacy version is mapped to migration id 'migration_{version}'. If that id is not registered in the current MigrationSet, the code rolls back and raises MigrationError, refusing to guess about the DB state.","triggerScenarios":"Upgrading from an old InvokeAI install whose database records legacy version numbers, where the running build has no migration registered with id migration_{legacy_version} (downgrade or divergent build).","commonSituations":"First launch of a modern InvokeAI against a very old database; downgraded install encountering a legacy DB; custom/forked migration sets that renamed migration IDs.","solutions":["Run the InvokeAI version that registers the missing migration_{version} first, then upgrade stepwise","Restore a DB backup consistent with the running version","Rebuild a fresh database and re-import models if the old DB is not needed"],"exampleFix":"# before: brand-new build against ancient db\ninvokeai-web --root /data/invokeai  # MigrationError: unknown legacy version 5\n# after: install the intermediate version that registers migration_5, run it, then upgrade\npip install invokeai==<version-with-migration_5> && invokeai-web --root /data/invokeai","handlingStrategy":"try-catch","validationCode":"import sqlite3\ncursor = sqlite3.connect(db_path).cursor()\nlegacy = [r[0] for r in cursor.execute(\"SELECT version FROM model_manager_migrations\")]\nregistered = {m.id for m in migration_set.migrations}\nmissing = [v for v in legacy if f\"migration_{v}\" not in registered]\nassert not missing, f\"legacy versions not in this build: {missing}\"","typeGuard":null,"tryCatchPattern":"try:\n    services.run_migrations()\nexcept MigrationError as e:\n    if \"unknown legacy migration version\" in str(e):\n        logger.critical(\"Legacy DB newer than this build: %s\", e)\n        raise\n    raise","preventionTips":["When upgrading very old installs, step through intermediate versions if required","Back up the legacy DB before first launch of a new build","Do not mix custom migration sets with an existing production DB"],"tags":["database","migrations","legacy","bootstrap"],"backgroundTag":"unknown-migration-version","analyzedSha":"0b6a024f2ff6a86bfb953dcdb9cc504ef7397a06","analyzedAt":"2026-08-29T04:46:49.967Z","schemaVersion":2},"datasetVersion":"2026-08-29T07:17:48.351Z"}