chroma-core/chroma · critical · InconsistentHashError

Inconsistent hashes in {path}:db hash was {db_hash}, source

Error message

Inconsistent hashes in {path}:db hash was {db_hash}, source has was {source_hash}. Was the migration file modified after being applied to the DB?

What it means

Chroma records a hash of each applied migration's SQL in the database; at startup it re-reads the shipped migration files and compares. InconsistentHashError (chromadb/db/migrations.py:226) fires when an already-applied migration's recorded hash differs from the file in the current install — i.e., the migration history and the code disagree about what was run. The database is left unusable for that component until reconciled.

Source

Thrown at chromadb/db/migrations.py:226

    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]:
    """Return a list of all migration present in the given directory, in ascending
    order. Filter by scope."""
    files = [
        _parse_migration_filename(dir.name, t.name, t)
        for t in dir.iterdir()
        if t.name.endswith(".sql")
    ]

View on GitHub (pinned to aecdd12c8a)

Solutions

Restore the original migration files: reinstall the exact chromadb version that created the database (pip install chromadb==<version>) so source hashes match again.
If history was intentionally rewritten or the mismatch is accepted, discard the persistent state (delete the persist/migration directory or the affected DB) and let migrations re-run — only viable when data loss is acceptable.
As a last resort, manually update the recorded hash in the migrations table to the new file's hash, after verifying the SQL changes are safe for already-migrated data.
Going forward, never edit applied migrations; always add a new higher-versioned migration file.

Defensive patterns

Strategy: try-catch

Type guard

def is_migration_hash_error(e: BaseException) -> bool:
    from chromadb.db.migrations import InconsistentHashError
    return isinstance(e, InconsistentHashError)

Try / catch

from chromadb.db.migrations import InconsistentHashError
try:
    app.start()  # triggers migrations
except InconsistentHashError as e:
    # fail fast with actionable guidance; do not auto-delete user data
    raise RuntimeError(f"Migration history mismatch: {e}. Restore the original chromadb version or rebuild the persist directory.") from e

Prevention

Never edit shipped migration files; add new versioned migrations only.
Pin one chromadb version per environment; upgrade deliberately, one version at a time.
Keep persist directories paired with the version that created them; don't share across installs.
Back up the persist/migration DB before version upgrades.

When it happens

Trigger: Editing a .sql migration file after it has been applied to a persistent database; upgrading/downgrading between Chroma builds whose migration files for the same version differ (e.g. patched releases, forks); copying a persist directory between installs from different sources; DB restored from a backup taken with a different build.

Common situations: Developers modifying shipped migrations instead of adding new ones; running a forked/vendored Chroma against a persist dir created by upstream; mixing persist data between docker image versions that patched the same migration; vendoring chromadb and later pulling upstream changes to migration SQL.

Related errors

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