{"record":{"id":"47c9845aaaa2346e","repo":"chroma-core/chroma","slug":"inconsistent-hashes-in-path-db-hash-was-db-hash","errorCode":null,"errorMessage":"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?","messagePattern":"Inconsistent hashes in (.+?):db hash was (.+?), source has was (.+?)\\. Was the migration file modified after being applied to the DB\\?","errorType":"exception","errorClass":"InconsistentHashError","httpStatus":null,"severity":"critical","filePath":"chromadb/db/migrations.py","lineNumber":226,"sourceCode":"    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]:\n    \"\"\"Return a list of all migration present in the given directory, in ascending\n    order. Filter by scope.\"\"\"\n    files = [\n        _parse_migration_filename(dir.name, t.name, t)\n        for t in dir.iterdir()\n        if t.name.endswith(\".sql\")\n    ]","sourceCodeStart":208,"sourceCodeEnd":244,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/chromadb/db/migrations.py#L208-L244","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":"def is_migration_hash_error(e: BaseException) -> bool:\n    from chromadb.db.migrations import InconsistentHashError\n    return isinstance(e, InconsistentHashError)","tryCatchPattern":"from chromadb.db.migrations import InconsistentHashError\ntry:\n    app.start()  # triggers migrations\nexcept InconsistentHashError as e:\n    # fail fast with actionable guidance; do not auto-delete user data\n    raise RuntimeError(f\"Migration history mismatch: {e}. Restore the original chromadb version or rebuild the persist directory.\") from e","preventionTips":["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."],"tags":["chroma","sqlite","migrations","schema-drift","startup"],"backgroundTag":"migration-checksum-mismatch","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}