{"record":{"id":"0ce4406451d383cd","repo":"juanfont/headscale","slug":"version-check-w","errorCode":null,"errorMessage":"version check: %w","messagePattern":"version check: %w","errorType":"console","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"hscontrol/db/db.go","lineNumber":63,"sourceCode":"\ntype HSDatabase struct {\n\tDB  *gorm.DB\n\tcfg *types.Config\n}\n\n// NewHeadscaleDatabase creates a new database connection and runs migrations.\n// It accepts the full configuration to allow migrations access to policy settings.\n//\n//nolint:gocyclo // complex database initialization with many migrations\nfunc NewHeadscaleDatabase(cfg *types.Config) (*HSDatabase, error) {\n\tdbConn, err := openDB(cfg.Database)\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\n\terr = checkVersionUpgradePath(dbConn)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"version check: %w\", err)\n\t}\n\n\tmigrations := gormigrate.New(\n\t\tdbConn,\n\t\tgormigrate.DefaultOptions,\n\t\t[]*gormigrate.Migration{\n\t\t\t// New migrations must be added as transactions at the end of this list.\n\t\t\t// Migrations start from v0.25.0. If upgrading from v0.24.x or earlier,\n\t\t\t// you must first upgrade to v0.25.1 before upgrading to this version.\n\n\t\t\t// v0.25.0\n\t\t\t{\n\t\t\t\t// Add a constraint to routes ensuring they cannot exist without a node.\n\t\t\t\tID: \"202501221827\",\n\t\t\t\tMigrate: func(tx *gorm.DB) error {\n\t\t\t\t\t// Remove any invalid routes associated with a node that does not exist.\n\t\t\t\t\tif tx.Migrator().HasTable(&types.Route{}) && tx.Migrator().HasTable(&types.Node{}) { //nolint:staticcheck // SA1019: Route kept for migrations\n\t\t\t\t\t\terr := tx.Exec(\"delete from routes where node_id not in (select id from nodes)\").Error","sourceCodeStart":45,"sourceCodeEnd":81,"githubUrl":"https://github.com/juanfont/headscale/blob/565fd254d06c4c7f9a8cad1714a43445c79ba420/hscontrol/db/db.go#L45-L81","documentation":"Returned by NewHeadscaleDatabase when checkVersionUpgradePath rejects the existing database version before any migration runs. Headscale only supports specific upgrade paths (e.g. pre-v0.25 databases must first be upgraded to v0.25.1, per the comment above the migration list); downgrades and multi-step jumps are refused to protect schema integrity.","triggerScenarios":"Starting a new headscale binary against a database written by a much older release (pre-v0.25), or pointing a newer binary at a database created by a NEWER version (downgrade). The wrapped error from versioncheck.go names the offending version.","commonSituations":"Rolling back a headscale upgrade while keeping the same database; restoring an old database backup onto a new binary; skipping several releases in one upgrade.","solutions":["Read the wrapped message to see the database's current version vs the supported range.","To upgrade from pre-v0.25: first run v0.25.1 against the database, then the target version.","To downgrade: restore a database backup taken before the upgrade - headscale will not migrate backwards.","Never point two major versions at the same database file."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"hsdb, err := db.NewHeadscaleDatabase(cfg)\nif err != nil {\n    if strings.Contains(err.Error(), \"version check\") {\n        // database version is unsupported: stop, back up, and upgrade stepwise\n        log.Fatal().Err(err).Msg(\"unsupported database version - upgrade via the documented path, do not delete the DB\")\n    }\n    return err\n}","preventionTips":["Back up the database before every headscale upgrade.","Upgrade through supported intermediate versions (pre-v0.25 must go via v0.25.1).","Never run a binary older than the database that wrote it.","Run the same headscale version for server and CLI against a shared database."],"tags":["database","migration","versioning","startup"],"backgroundTag":null,"analyzedSha":"565fd254d06c4c7f9a8cad1714a43445c79ba420","analyzedAt":"2026-08-15T13:12:30.133Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}