{"record":{"id":"b7895ce95d1593d7","repo":"chroma-core/chroma","slug":"migrations-have-not-been-initialized","errorCode":null,"errorMessage":"Migrations have not been initialized","messagePattern":"Migrations have not been initialized","errorType":"exception","errorClass":"UninitializedMigrationsError","httpStatus":null,"severity":"error","filePath":"chromadb/db/migrations.py","lineNumber":147,"sourceCode":"        \"\"\"Apply a single migration to the database\"\"\"\n        pass\n\n    def initialize_migrations(self) -> None:\n        \"\"\"Initialize migrations for this DB\"\"\"\n        migrate = self._settings.require(\"migrations\")\n\n        if migrate == \"validate\":\n            self.validate_migrations()\n\n        if migrate == \"apply\":\n            self.apply_migrations()\n\n    @trace_method(\"MigratableDB.validate_migrations\", OpenTelemetryGranularity.ALL)\n    def validate_migrations(self) -> None:\n        \"\"\"Validate all migrations and throw an exception if there are any unapplied\n        migrations in the source repo.\"\"\"\n        if not self.migrations_initialized():\n            raise UninitializedMigrationsError()\n        for dir in self.migration_dirs():\n            db_migrations = self.db_migrations(dir)\n            source_migrations = find_migrations(\n                dir,\n                self.migration_scope(),\n                self._settings.require(\"migrations_hash_algorithm\"),\n            )\n            unapplied_migrations = verify_migration_sequence(\n                db_migrations, source_migrations\n            )\n            if len(unapplied_migrations) > 0:\n                version = unapplied_migrations[0][\"version\"]\n                raise UnappliedMigrationsError(dir=dir.name, version=version)\n\n    @trace_method(\"MigratableDB.apply_migrations\", OpenTelemetryGranularity.ALL)\n    def apply_migrations(self) -> None:\n        \"\"\"Validate existing migrations, and apply all new ones.\"\"\"\n        self.setup_migrations()","sourceCodeStart":129,"sourceCodeEnd":165,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/chromadb/db/migrations.py#L129-L165","documentation":"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.","triggerScenarios":"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'.","commonSituations":"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.","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."],"exampleFix":"// before\nsettings = Settings(persist_directory='./data', migrations='validate')  # fresh dir -> error\n\n// after\nsettings = Settings(persist_directory='./data', migrations='apply')  # first boot\n# subsequent boots may use migrations='validate'","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"from chromadb.db.migrations import UninitializedMigrationsError\n\ntry:\n    db.validate_migrations()\nexcept UninitializedMigrationsError:\n    # fresh/wiped DB: create the migrations table and apply everything once\n    db.setup_migrations()\n    db.apply_migrations()","preventionTips":["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."],"tags":["migrations","database","startup","sqlite"],"backgroundTag":"migrations-not-initialized","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}