What causes "Migrations have not been initialized" in chroma-core/chroma?

Use the default migrations='apply' at least once: it creates the migrations table and applies all migrations.

chroma-core/chroma · error · UninitializedMigrationsError

Migrations have not been initialized

Error message

Migrations have not been initialized

What it means

MigratableDB.validate_migrations (chromadb/db/migrations.py) first calls migrations_initialized() to confirm the migrations bookkeeping table exists; if it does not, it raises UninitializedMigrationsError. Validation mode runs when Settings.migrations == 'validate', so this fires when a brand-new (or wiped) database is booted in validate mode - there is no migration history to validate against yet.

Source

Thrown at chromadb/db/migrations.py:147

        """Apply a single migration to the database"""
        pass

    def initialize_migrations(self) -> None:
        """Initialize migrations for this DB"""
        migrate = self._settings.require("migrations")

        if migrate == "validate":
            self.validate_migrations()

        if migrate == "apply":
            self.apply_migrations()

    @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()

View on GitHub (pinned to aecdd12c8a)

Solutions

Use the default migrations='apply' at least once: it creates the migrations table and applies all migrations.
Or bootstrap explicitly: run one startup with 'apply', then switch the setting to 'validate' for subsequent boots.
If the database should already be initialized, verify the persist path / DB connection points at the right location.

Example fix

// before
settings = Settings(persist_directory='./data', migrations='validate')  # fresh dir -> error

// after
settings = Settings(persist_directory='./data', migrations='apply')  # first boot
# subsequent boots may use migrations='validate'

Defensive patterns

Strategy: try-catch

Try / catch

from chromadb.db.migrations import UninitializedMigrationsError

try:
    db.validate_migrations()
except UninitializedMigrationsError:
    # fresh/wiped DB: create the migrations table and apply everything once
    db.setup_migrations()
    db.apply_migrations()

Prevention

Use migrations='apply' (the default) for first boot; switch to 'validate' only for steady state.
Point persist paths explicitly so a typo never creates a fresh, uninitialized DB in validate mode.
Smoke-test startup in CI with the same migrations mode you run in production.

When it happens

Trigger: Settings(migrations='validate') against a fresh SQLite file or empty Postgres schema; a database previously created with migrations='none' (which skips setup_migrations) later opened with 'validate'.

Common situations: CI containers starting with an empty volume while config demands validation; deployments that switched from migrations='none' to 'validate' over the same data directory; pointing at the wrong persist path so a new DB gets created.

Related errors

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