juanfont/headscale · error

major version change not supported

Error message

major version change not supported

What it means

Error "major version change not supported" thrown in juanfont/headscale.

Source

Thrown at hscontrol/db/versioncheck.go:21

import (
	"errors"
	"fmt"
	"regexp"
	"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 {

View on GitHub (pinned to 565fd254d0)

Solutions

1. Inspect the wrapped error for the underlying cause and correct the failing condition (major version change not supported); 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 (major version change not supported); retry the operation after fixing the input, configuration, or environment.

When it happens

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

Common situations: A database from a different major headscale version cannot be opened. Follow the documented upgrade path between major versions instead of pointing the new binary at the old database.

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