chroma-core/chroma · critical · InconsistentVersionError

Inconsistent migration versions in {dir}:db version was {db_

Error message

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?

What it means

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.

Source

Thrown at chromadb/db/migrations.py:219


def verify_migration_sequence(
    db_migrations: Sequence[Migration],
    source_migrations: Sequence[Migration],
) -> Sequence[Migration]:
    """Given a list of migrations already applied to a database, and a list of
    migrations from the source code, validate that the applied migrations are correct
    and match the expected migrations.

    Throws an exception if any migrations are missing, out of order, or if the source
    hash does not match.

    Returns a list of all unapplied migrations, or an empty list if all migrations are
    applied and the database is up to date."""

    for db_migration, source_migration in zip(db_migrations, source_migrations):
        if db_migration["version"] != source_migration["version"]:
            raise InconsistentVersionError(
                dir=db_migration["dir"],
                db_version=db_migration["version"],
                source_version=source_migration["version"],
            )

        if db_migration["hash"] != source_migration["hash"]:
            raise InconsistentHashError(
                path=db_migration["dir"] + "/" + db_migration["filename"],
                db_hash=db_migration["hash"],
                source_hash=source_migration["hash"],
            )

    return source_migrations[len(db_migrations) :]


def find_migrations(
    dir: Traversable, scope: str, hash_alg: str = "md5"
) -> Sequence[Migration]:

View on GitHub (pinned to aecdd12c8a)

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.

Example fix

# before (fork renumbered migration 00004 as 00003)
# db applied:  00001,00002,00004   source now: 00001,00002,00003 -> InconsistentVersionError

# after
# restore original files/numbering; append new migrations above the max applied version:
# 00001..00004 (unchanged) + 00005-new-change.sqlite.sql

Defensive patterns

Strategy: try-catch

Try / catch

from chromadb.db.migrations import InconsistentVersionError

try:
    db.apply_migrations()
except InconsistentVersionError as e:
    # DB and source histories diverged: do NOT hack around it blindly
    logger.error('migration history diverged in %s (db=%s source=%s); restore original files or rebuild from backup',
                 e.dir, getattr(e, 'db_version', '?'), getattr(e, 'source_version', '?'))
    raise

Prevention

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.

When it happens

Trigger: 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.

Common situations: Switching between a fork and upstream over the same data; teams editing migration files post-release; long-lived dev databases kept across major refactors.

Related errors

AI-assisted analysis of chroma-core/chroma@aecdd12c8a (2026-08-16). Data as JSON: /api/errors/37c01107983e28f6. Report an issue: GitHub.