juanfont/headscale · error

version does not follow semver major.minor.patch format

Error message

version does not follow semver major.minor.patch format

What it means

Error "version does not follow semver major.minor.patch format" thrown in juanfont/headscale.

Source

Thrown at hscontrol/db/versioncheck.go:25

	"strconv"
	"strings"
	"time"

	"github.com/juanfont/headscale/hscontrol/types"
	"github.com/rs/zerolog/log"
	"gorm.io/gorm"
	"gorm.io/gorm/clause"
)

var errVersionUpgrade = errors.New("version upgrade not supported")

var errVersionDowngrade = errors.New("version downgrade not supported")

var errVersionMajorChange = errors.New("major version change not supported")

var errVersionParse = errors.New("cannot parse version")

var errVersionFormat = errors.New(
	"version does not follow semver major.minor.patch format",
)

// DatabaseVersion tracks the headscale version that last
// successfully started against this database.
// It is a single-row table (ID is always 1).
type DatabaseVersion struct {
	ID        uint   `gorm:"primaryKey"`
	Version   string `gorm:"not null"`
	UpdatedAt time.Time
}

// semver holds parsed major.minor.patch components.
type semver struct {
	Major int
	Minor int
	Patch int
}

View on GitHub (pinned to 565fd254d0)

Solutions

1. Inspect the wrapped error for the underlying cause and correct the failing condition (version does not follow semver major.minor.patch format); retry the operation after fixing the input, configuration, or environment.

Example fix

Inspect the wrapped error for the underlying cause and correct the failing condition (version does not follow semver major.minor.patch format); retry the operation after fixing the input, configuration, or environment.

When it happens

Trigger: Thrown at hscontrol/db/versioncheck.go:25 when the library encounters an invalid state.

Common situations: The version string does not match semver major.minor.patch. Use full three-component versions (e.g. 0.26.1) when embedding or comparing headscale versions.

AI-assisted analysis of juanfont/headscale@565fd254d0 (2026-08-15). Data as JSON: /api/errors/e6455ce54cbe3d02. Report an issue: GitHub.