Found a migration file that does not match the file pattern:

Error message

Found a migration file that does not match the file pattern: filename=%s pattern=%s

What it means

During findMigrations, every file in the migrations directory/filesystem is parsed with parseMigrationFilename, which returns nil for non-matching names. When a file does not match MigrationFileRegexp (^\d+_([^.]+)(\.[a-z0-9]+)?(\.autocommit)?\.(up|down)\.(sql)$), this error (oryx/popx/migration_box.go:299) names the offending filename and the expected pattern so the developer can fix or remove the file.

Source

Thrown at oryx/popx/migration_box.go:299

			return nil
		}

		if path.Ext(info.Name()) != ".sql" {
			mb.l.Tracef("ignoring non SQL file: %s", info.Name())
			return nil
		}

		details, err := parseMigrationFilename(info.Name())
		if err != nil {
			if errors.Is(err, errUnsupportedMigrationDialect) {
				mb.l.Debugf("Ignoring migration file %s because its dialect is not supported: %s", info.Name(), err.Error())
				return nil
			}
			return errors.WithStack(err)
		}

		if details == nil {
			return errors.Errorf("Found a migration file that does not match the file pattern: filename=%s pattern=%s", info.Name(), MigrationFileRegexp)
		}

		content, err := fs.ReadFile(dir, p)
		if err != nil {
			return errors.WithStack(err)
		}

		mf := Migration{
			Path:       p,
			Version:    details.Version,
			Name:       details.Name,
			DBType:     details.DBType,
			Direction:  details.Direction,
			Type:       details.Type,
			Content:    string(content),
			Autocommit: details.Autocommit,
		}

View on GitHub (pinned to 4174065ffb)

Solutions

Rename the offending file to match the pattern: <version>_<name>[.<dialect>][.autocommit].<up|down>.sql
Delete or move non-migration files (backups, READMEs, editor temp files) out of the migrations directory
Verify with the regex MigrationFileRegexp that your filename matches before deploying

Example fix

// before (no version prefix / wrong extension)
add_users_table.txt
// after
20240101000000_add_users_table.up.sql

Defensive patterns

Strategy: validation

Validate before calling

var MigrationFileRegexp = regexp.MustCompile(`^(\d+)_([^.]+)(\.[a-z0-9]+)?(\.autocommit)?\.(up|down)\.(sql)$`)
// fs.WalkDir over your migrations dir; fail fast on non-conforming files before starting the app
if !MigrationFileRegexp.MatchString(info.Name()) {
    return fmt.Errorf("file %s does not match migration pattern", info.Name())
}

Try / catch

err := mb.Exec(ctx, conn)
if err != nil {
    if strings.Contains(err.Error(), "does not match the file pattern") {
        return fmt.Errorf("fix or remove the offending file in the migrations directory: %v", err)
    }
    return err
}

Prevention

Keep the migrations directory clean: no editor backups, .DS_Store, READMEs, or partial files
Lint migration filenames in CI before building the embedded FS
Follow the strict naming scheme: <version>_<name>[.<dialect>][.autocommit].<up|down>.sql

When it happens

Trigger: A file exists in the migrations directory whose name does not satisfy MigrationFileRegexp — missing version number, wrong extension (e.g. .sql.gz, .txt), missing direction, or stray characters in the name.

Common situations: Editor backup files (migration.sql~, .DS_Store) or partial downloads in the migrations folder; hand-created migrations missing the version prefix; renaming tools that altered extensions.

Related errors

AI-assisted analysis of ory/hydra@4174065ffb (2026-09-03). Data as JSON: /api/errors/374faa2423bb95a2. Report an issue: GitHub.