chroma-core/chroma · error · UnappliedMigrationsError

Unapplied migrations in {dir}, starting with version {versio

Error message

Unapplied migrations in {dir}, starting with version {version}

What it means

With Settings.migrations='validate', after verifying consistency Chroma diffs the applied migrations against the packaged source migrations; any pending ones raise UnappliedMigrationsError with dir (the migration directory, e.g. 'meta' or 'embeddings') and version (the first unapplied migration number). It means the installed chromadb code is newer than the database schema - new SQL migrations exist that the DB has not applied.

Source

Thrown at chromadb/db/migrations.py:160

    @trace_method("MigratableDB.validate_migrations", OpenTelemetryGranularity.ALL)
    def validate_migrations(self) -> None:
        """Validate all migrations and throw an exception if there are any unapplied
        migrations in the source repo."""
        if not self.migrations_initialized():
            raise UninitializedMigrationsError()
        for dir in self.migration_dirs():
            db_migrations = self.db_migrations(dir)
            source_migrations = find_migrations(
                dir,
                self.migration_scope(),
                self._settings.require("migrations_hash_algorithm"),
            )
            unapplied_migrations = verify_migration_sequence(
                db_migrations, source_migrations
            )
            if len(unapplied_migrations) > 0:
                version = unapplied_migrations[0]["version"]
                raise UnappliedMigrationsError(dir=dir.name, version=version)

    @trace_method("MigratableDB.apply_migrations", OpenTelemetryGranularity.ALL)
    def apply_migrations(self) -> None:
        """Validate existing migrations, and apply all new ones."""
        self.setup_migrations()
        for dir in self.migration_dirs():
            db_migrations = self.db_migrations(dir)
            source_migrations = find_migrations(
                dir,
                self.migration_scope(),
                self._settings.require("migrations_hash_algorithm"),
            )
            unapplied_migrations = verify_migration_sequence(
                db_migrations, source_migrations
            )
            with self.tx() as cur:
                for migration in unapplied_migrations:
                    self.apply_migration(cur, migration)

View on GitHub (pinned to aecdd12c8a)

Solutions

1. Run one boot (or a one-off job) with migrations='apply' (the default) to bring the DB up to date, then restore 'validate'.
2. Or roll back the chromadb package to the version whose migration set matches the DB.
3. In distributed setups, run migrations from a single deploy job before rolling out new code to replicas.

Example fix

# before
export CHROMA_MIGRATIONS=validate  # after package upgrade -> UnappliedMigrationsError

# after
export CHROMA_MIGRATIONS=apply   # one boot: applies pending migrations
# then, for steady state:
export CHROMA_MIGRATIONS=validate

from chromadb.db.migrations import UnappliedMigrationsError

try:
    db.validate_migrations()  # or boot with Settings(migrations='validate')
except UnappliedMigrationsError as e:
    logger.warning('schema behind source in %s from version %s; applying', e.dir, e.version)
    db.apply_migrations()  # or: run a one-off job with Settings(migrations='apply')

When it happens

Trigger: Upgrading the chromadb package while keeping a persisted DB created by an older version, with migrations pinned to 'validate'; read-only deployments that intentionally defer schema changes; rolling upgrades where app replicas outpace the DB.

Common situations: Prod configs that pin migrations='validate' for schema safety, then a version bump ships new migrations; staging restores of old data dirs run by new code.

Related errors

• Inconsistent migration versions in {dir}:db version was {db_
• Chroma error response missing required 'message' field: {res
• Could not build embedding function {ef_config['name']} from
• Migrations have not been initialized
• Invalid migration filename: {filename}

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