ory/hydra · error

unknown migration direction %q for %q

Error message

unknown migration direction %q for %q

What it means

Migration filenames encode the direction as .up. or .down.; findMigrations appends each parsed migration to migrationsUp or migrationsDown based on details.Direction. If a parsed match carries any other direction, this error (oryx/popx/migration_box.go:326) reports the unknown direction together with the filename. Given the regex only captures up|down, this is a defensive check against corrupted parse results.

Source

Thrown at oryx/popx/migration_box.go:326

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

		mf.Runner = runner(content)

		switch details.Direction {
		case "up":
			mb.migrationsUp = append(mb.migrationsUp, mf)
		case "down":
			mb.migrationsDown = append(mb.migrationsDown, mf)
		default:
			return errors.Errorf("unknown migration direction %q for %q", details.Direction, info.Name())
		}
		return nil
	})

	// Sort descending.
	sort.Sort(mb.migrationsDown)
	slices.Reverse(mb.migrationsDown)

	// Sort ascending.
	sort.Sort(mb.migrationsUp)

	return errors.WithStack(err)
}

// hasDownMigrationWithVersion checks if there is a migration with the given
// version.
func (mb *MigrationBox) hasDownMigrationWithVersion(version string) bool {
	for _, down := range mb.migrationsDown {

View on GitHub (pinned to 4174065ffb)

Solutions

1. Check the migration filename contains a valid .up. or .down. direction segment and fix it
2. If you forked or patched the parsing logic, ensure the direction capture is limited to (up|down)
3. Rebuild the binary/embed FS so the migrations directory contents match the expected format

Example fix

// before
20240101000000_add_users_table.all.sql (no direction)
// after
20240101000000_add_users_table.up.sql

re := regexp.MustCompile(`^(\d+)_([^.]+)(\.[a-z0-9]+)?(\.autocommit)?\.(up|down)\.(sql)$`)
if !re.MatchString(filename) { return fmt.Errorf("missing valid up/down direction in %q", filename) }

err := mb.Run(ctx)
if err != nil {
    if strings.Contains(err.Error(), "unknown migration direction") {
        return fmt.Errorf("migration filename must end in .up.sql or .down.sql: %v", err)
    }
    return err
}

When it happens

Trigger: A migration's parsed Direction is neither "up" nor "down" while loading migrations from a filesystem/directory.

Common situations: Custom/modified file-pattern parsing producing unexpected direction values; a monkey-patched or divergent regex in a fork; corrupted embedded filesystem entries.

Related errors

• %s
• invalid database type %q, expected "all" because fizz is dat
• invalid autocommit flag %q
• Found a migration file that does not match the file pattern:
• unsupported dialect

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