semaphoreui/semaphore · error

migration version is empty

Error message

migration version is empty

What it means

Migration.Validate requires a Migration to carry a non-empty Version string. Database migrations are identified and ordered by their dotted version string; an empty version cannot be tracked in the migrations table, so migrations load/init code rejects it before any comparison or execution.

Solutions

1. Ensure every migration file/record carries a version in its name or Version field (e.g. "1.0")
2. Check the migration loading/glob code so only properly named migration files are collected
3. When constructing migrations programmatically, always set Version before Validate

Example fix

// before
m := db.Migration{Script: "INSERT ..."}
if err := m.Validate(); err != nil { ... }
// after
m := db.Migration{Version: "1.5", Script: "INSERT ..."}
if err := m.Validate(); err != nil { ... }

if strings.TrimSpace(m.Version) == "" {
	return errors.New("migration must have a non-empty version")
}

func hasVersion(m db.Migration) bool {
	return strings.TrimSpace(m.Version) != ""
}

if err := m.Validate(); err != nil {
	if strings.Contains(err.Error(), "migration version is empty") {
		return fmt.Errorf("bad migration: %w", err)
	}
	return err
}

When it happens

Trigger: A migration source (embedded FS, filesystem scan, or programmatically constructed Migration struct) yields a Migration with Version == "", which is then validated during schema maintenance (migration listing/application path).

Common situations: A migration file named without the expected version prefix; an embedded-migrations glob matching a non-migration file; code constructing Migration{} without setting Version; packaging/build stripping migration metadata.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

• invalid migration version format
• name can not be empty
• missing secret
• invalid environment secret type
• must be valid JSON

AI-assisted analysis of semaphoreui/semaphore@1774ccb71a (2026-09-07). Data as JSON: /api/errors/35f4f463be7327df. Report an issue: GitHub.

Appendix: source

Thrown at db/Migration.go:145

		{Version: "2.18.4"},
		{Version: "2.18.5"},
		{Version: "2.18.6"},
		{Version: "2.18.7"},
		{Version: "2.18.15"},
		{Version: "2.19.2"},
		{Version: "2.19.11"},
		{Version: "2.19.12"},
		{Version: "2.19.14"},
		{Version: "2.20.0"},
		{Version: "2.20.1"},
	}

	return append(initScripts, commonScripts...)
}

func (m Migration) Validate() error {
	if m.Version == "" {
		return fmt.Errorf("migration version is empty")
	}

	return nil
}

type MigrationVersion struct {
	Major int
	Minor int
	Patch int
}

func (m Migration) ParseVersion() (res MigrationVersion, err error) {

	parts := strings.Split(m.Version, ".")

	if len(parts) < 2 {
		err = fmt.Errorf("invalid migration version format %s", m.Version)
		return

View on GitHub (pinned to 1774ccb71a)