{"record":{"id":"37c01107983e28f6","repo":"chroma-core/chroma","slug":"inconsistent-migration-versions-in-dir-db-versio","errorCode":null,"errorMessage":"Inconsistent migration versions in {dir}:db version was {db_version}, source version was {source_version}. Has the migration sequence been modified since being applied to the DB?","messagePattern":"Inconsistent migration versions in (.+?):db version was (.+?), source version was (.+?)\\. Has the migration sequence been modified since being applied to the DB\\?","errorType":"exception","errorClass":"InconsistentVersionError","httpStatus":null,"severity":"critical","filePath":"chromadb/db/migrations.py","lineNumber":219,"sourceCode":"\n\ndef verify_migration_sequence(\n    db_migrations: Sequence[Migration],\n    source_migrations: Sequence[Migration],\n) -> Sequence[Migration]:\n    \"\"\"Given a list of migrations already applied to a database, and a list of\n    migrations from the source code, validate that the applied migrations are correct\n    and match the expected migrations.\n\n    Throws an exception if any migrations are missing, out of order, or if the source\n    hash does not match.\n\n    Returns a list of all unapplied migrations, or an empty list if all migrations are\n    applied and the database is up to date.\"\"\"\n\n    for db_migration, source_migration in zip(db_migrations, source_migrations):\n        if db_migration[\"version\"] != source_migration[\"version\"]:\n            raise InconsistentVersionError(\n                dir=db_migration[\"dir\"],\n                db_version=db_migration[\"version\"],\n                source_version=source_migration[\"version\"],\n            )\n\n        if db_migration[\"hash\"] != source_migration[\"hash\"]:\n            raise InconsistentHashError(\n                path=db_migration[\"dir\"] + \"/\" + db_migration[\"filename\"],\n                db_hash=db_migration[\"hash\"],\n                source_hash=source_migration[\"hash\"],\n            )\n\n    return source_migrations[len(db_migrations) :]\n\n\ndef find_migrations(\n    dir: Traversable, scope: str, hash_alg: str = \"md5\"\n) -> Sequence[Migration]:","sourceCodeStart":201,"sourceCodeEnd":237,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/chromadb/db/migrations.py#L201-L237","documentation":"verify_migration_sequence (chromadb/db/migrations.py) walks applied (DB) and source migrations in lockstep; if the i-th applied version differs from the i-th source version, the histories have diverged and InconsistentVersionError is raised. Typically a migration was inserted, deleted, or renumbered after the database already applied the original sequence. Chroma refuses to continue rather than guess how to reconcile.","triggerScenarios":"Inserting a new migration with an old version number into a sequence already applied to a DB; deleting or renumbering shipped migrations; running a modified fork against a DB migrated by upstream chromadb (or vice versa); rebasing two branches that both added migrations with colliding version numbers.","commonSituations":"Switching between a fork and upstream over the same data; teams editing migration files post-release; long-lived dev databases kept across major refactors.","solutions":["Restore the exact migration files the database was migrated with (version numbering included), then append new migrations above the current max version.","For disposable data, delete the SQLite file / drop the schema and let Chroma re-apply all migrations from scratch.","For valuable data, back up the DB first and reconcile the histories manually before retrying."],"exampleFix":"# before (fork renumbered migration 00004 as 00003)\n# db applied:  00001,00002,00004   source now: 00001,00002,00003 -> InconsistentVersionError\n\n# after\n# restore original files/numbering; append new migrations above the max applied version:\n# 00001..00004 (unchanged) + 00005-new-change.sqlite.sql","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"from chromadb.db.migrations import InconsistentVersionError\n\ntry:\n    db.apply_migrations()\nexcept InconsistentVersionError as e:\n    # DB and source histories diverged: do NOT hack around it blindly\n    logger.error('migration history diverged in %s (db=%s source=%s); restore original files or rebuild from backup',\n                 e.dir, getattr(e, 'db_version', '?'), getattr(e, 'source_version', '?'))\n    raise","preventionTips":["Treat migrations as append-only: never renumber, delete, or reorder applied files.","Allocate new versions above the current max in the shared repo, not per-branch.","Back up the database before upgrading chromadb in long-lived environments."],"tags":["migrations","version-mismatch","schema","data-integrity"],"backgroundTag":"migration-version-mismatch","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}