chroma-core/chroma · error · InvalidMigrationFilename

Invalid migration filename: {filename}

Error message

Invalid migration filename: {filename}

What it means

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.

Source

Thrown at chromadb/db/migrations.py:192

                db_migrations, source_migrations
            )
            with self.tx() as cur:
                for migration in unapplied_migrations:
                    self.apply_migration(cur, migration)


# Format is <version>-<name>.<scope>.sql
# e.g, 00001-users.sqlite.sql
filename_regex = re.compile(r"(\d+)-(.+)\.(.+)\.sql")


def _parse_migration_filename(
    dir: str, filename: str, path: Traversable
) -> MigrationFile:
    """Parse a migration filename into a MigrationFile object"""
    match = filename_regex.match(filename)
    if match is None:
        raise InvalidMigrationFilename("Invalid migration filename: " + filename)
    version, _, scope = match.groups()
    return {
        "path": path,
        "dir": dir,
        "filename": filename,
        "version": int(version),
        "scope": scope,
    }


def verify_migration_sequence(
    db_migrations: Sequence[Migration],
    source_migrations: Sequence[Migration],
) -> Sequence[Migration]:
    """Given a list of migrations already applied to a database, and a list of
    migrations from the source code, validate that the applied migrations are correct
    and match the expected migrations.

View on GitHub (pinned to aecdd12c8a)

Solutions

1. Rename to <zero-padded version>-<description>.<scope>.sql where scope matches the DB's migration_scope() ('sqlite' or 'pgsql').
2. Keep every non-migration file (readmes, notes, backups) out of migration directories.
3. Never rename or renumber an already-applied migration - add a new one with a higher version instead.

Example fix

# before
migrations/meta/00006-add-idx.sql          # Invalid migration filename

# after
migrations/meta/00006-add-idx.sqlite.sql  # <version>-<name>.<scope>.sql

import re
from pathlib import Path

MIGRATION_RE = re.compile(r'(\d+)-(.+)\.(.+)\.sql')

bad = [f.name for f in Path(mig_dir).iterdir() if f.is_file() and not MIGRATION_RE.match(f.name)]
assert not bad, f'invalid migration filenames in {mig_dir}: {bad}'

from chromadb.db.migrations import InvalidMigrationFilename

try:
    _ = find_migrations(dir, scope, hash_alg)
except InvalidMigrationFilename as e:
    raise RuntimeError(f'fix migration filename to <version>-<name>.<scope>.sql: {e}') from e

When it happens

Trigger: 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.

Common situations: Forks or contributors adding packaged migrations without following the convention; tools that leave temp files in package resource dirs; IDE auto-renaming on refactor.

Related errors

• Migrations have not been initialized
• Unapplied migrations in {dir}, starting with version {versio
• Inconsistent migration versions in {dir}:db version was {db_
• Inconsistent hashes in {path}:db hash was {db_hash}, source
• No migration file found for dir {file['dir']} with filename

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