{"record":{"id":"98c65444a4415816","repo":"chroma-core/chroma","slug":"unapplied-migrations-in-dir-starting-with-versi","errorCode":null,"errorMessage":"Unapplied migrations in {dir}, starting with version {version}","messagePattern":"Unapplied migrations in (.+?), starting with version (.+?)","errorType":"exception","errorClass":"UnappliedMigrationsError","httpStatus":null,"severity":"error","filePath":"chromadb/db/migrations.py","lineNumber":160,"sourceCode":"    @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()\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            with self.tx() as cur:\n                for migration in unapplied_migrations:\n                    self.apply_migration(cur, migration)","sourceCodeStart":142,"sourceCodeEnd":178,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/chromadb/db/migrations.py#L142-L178","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Run one boot (or a one-off job) with migrations='apply' (the default) to bring the DB up to date, then restore 'validate'.","Or roll back the chromadb package to the version whose migration set matches the DB.","In distributed setups, run migrations from a single deploy job before rolling out new code to replicas."],"exampleFix":"# before\nexport CHROMA_MIGRATIONS=validate  # after package upgrade -> UnappliedMigrationsError\n\n# after\nexport CHROMA_MIGRATIONS=apply   # one boot: applies pending migrations\n# then, for steady state:\nexport CHROMA_MIGRATIONS=validate","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"from chromadb.db.migrations import UnappliedMigrationsError\n\ntry:\n    db.validate_migrations()  # or boot with Settings(migrations='validate')\nexcept UnappliedMigrationsError as e:\n    logger.warning('schema behind source in %s from version %s; applying', e.dir, e.version)\n    db.apply_migrations()  # or: run a one-off job with Settings(migrations='apply')","preventionTips":["Run migrations as an explicit deploy step (single job, migrations='apply') before rolling new code out.","Pin the chromadb version per environment so code and DB schema advance together.","Monitor the applied migration version after deploys to catch drift early."],"tags":["migrations","schema-upgrade","version-mismatch"],"backgroundTag":"unapplied-migrations","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}