{"record":{"id":"f2760dad25875bcd","repo":"chroma-core/chroma","slug":"invalid-migration-filename-filename","errorCode":null,"errorMessage":"Invalid migration filename: {filename}","messagePattern":"Invalid migration filename: (.+?)","errorType":"exception","errorClass":"InvalidMigrationFilename","httpStatus":null,"severity":"error","filePath":"chromadb/db/migrations.py","lineNumber":192,"sourceCode":"                db_migrations, source_migrations\n            )\n            with self.tx() as cur:\n                for migration in unapplied_migrations:\n                    self.apply_migration(cur, migration)\n\n\n# Format is <version>-<name>.<scope>.sql\n# e.g, 00001-users.sqlite.sql\nfilename_regex = re.compile(r\"(\\d+)-(.+)\\.(.+)\\.sql\")\n\n\ndef _parse_migration_filename(\n    dir: str, filename: str, path: Traversable\n) -> MigrationFile:\n    \"\"\"Parse a migration filename into a MigrationFile object\"\"\"\n    match = filename_regex.match(filename)\n    if match is None:\n        raise InvalidMigrationFilename(\"Invalid migration filename: \" + filename)\n    version, _, scope = match.groups()\n    return {\n        \"path\": path,\n        \"dir\": dir,\n        \"filename\": filename,\n        \"version\": int(version),\n        \"scope\": scope,\n    }\n\n\ndef verify_migration_sequence(\n    db_migrations: Sequence[Migration],\n    source_migrations: Sequence[Migration],\n) -> Sequence[Migration]:\n    \"\"\"Given a list of migrations already applied to a database, and a list of\n    migrations from the source code, validate that the applied migrations are correct\n    and match the expected migrations.\n","sourceCodeStart":174,"sourceCodeEnd":210,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/chromadb/db/migrations.py#L174-L210","documentation":"Migration filenames must match <version>-<name>.<scope>.sql - the regex (\\d+)-(.+)\\.(.+)\\.sql, e.g. 00001-users.sqlite.sql. _parse_migration_filename raises InvalidMigrationFilename ('Invalid migration filename: <file>') for anything else: wrong separator, missing scope suffix, non-SQL extension, or a stray file (README, .DS_Store) inside a registered migration directory.","triggerScenarios":"Adding a custom migration named 00006-fix.sql (missing .sqlite scope) or 00006_fix.sqlite.sql (underscore instead of hyphen); dropping a README.md or editor backup file into a migrations package directory; renaming an existing migration file.","commonSituations":"Forks or contributors adding packaged migrations without following the convention; tools that leave temp files in package resource dirs; IDE auto-renaming on refactor.","solutions":["Rename to <zero-padded version>-<description>.<scope>.sql where scope matches the DB's migration_scope() ('sqlite' or 'pgsql').","Keep every non-migration file (readmes, notes, backups) out of migration directories.","Never rename or renumber an already-applied migration - add a new one with a higher version instead."],"exampleFix":"# before\nmigrations/meta/00006-add-idx.sql          # Invalid migration filename\n\n# after\nmigrations/meta/00006-add-idx.sqlite.sql  # <version>-<name>.<scope>.sql","handlingStrategy":"validation","validationCode":"import re\nfrom pathlib import Path\n\nMIGRATION_RE = re.compile(r'(\\d+)-(.+)\\.(.+)\\.sql')\n\nbad = [f.name for f in Path(mig_dir).iterdir() if f.is_file() and not MIGRATION_RE.match(f.name)]\nassert not bad, f'invalid migration filenames in {mig_dir}: {bad}'","typeGuard":null,"tryCatchPattern":"from chromadb.db.migrations import InvalidMigrationFilename\n\ntry:\n    _ = find_migrations(dir, scope, hash_alg)\nexcept InvalidMigrationFilename as e:\n    raise RuntimeError(f'fix migration filename to <version>-<name>.<scope>.sql: {e}') from e","preventionTips":["Enforce the <version>-<name>.<scope>.sql convention with a repo lint/CI check over migration directories.","Keep migration directories free of non-SQL files (readmes, notes, editor backups).","Copy an existing migration file as a template when adding new ones."],"tags":["migrations","file-naming","convention"],"backgroundTag":"invalid-migration-filename","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}