{"record":{"id":"23ae7867793717b0","repo":"juanfont/headscale","slug":"headscale-version-s-cannot-be-used-with-a-databas-23ae78","errorCode":null,"errorMessage":"headscale version %s cannot be used with a database last used by %s, downgrading to a previous minor version is not supported, release page: https://github.com/juanfont/headscale/releases: %w","messagePattern":"headscale version (.+?) cannot be used with a database last used by (.+?), downgrading to a previous minor version is not supported, release page: https://github\\.com/juanfont/headscale/releases: %w","errorType":"console","errorClass":"errVersionDowngrade","httpStatus":null,"severity":"critical","filePath":"hscontrol/db/versioncheck.go","lineNumber":271,"sourceCode":"\t\t// Single minor version upgrade — allowed.\n\t\treturn nil\n\n\tcase minorDiff > 1:\n\t\t// Multi-minor upgrade — blocked.\n\t\treturn fmt.Errorf(\n\t\t\t\"headscale version %s cannot be used with a database last used by %s, \"+\n\t\t\t\t\"upgrading more than one minor version at a time is not supported, \"+\n\t\t\t\t\"please upgrade to the latest v%d.%d.x release first, then to %s, \"+\n\t\t\t\t\"release page: https://github.com/juanfont/headscale/releases: %w\",\n\t\t\tcurrentVersion, storedVersion,\n\t\t\tstored.Major, stored.Minor+1,\n\t\t\tcurrent.String(),\n\t\t\terrVersionUpgrade,\n\t\t)\n\n\tdefault:\n\t\t// minorDiff < 0 — any minor downgrade is blocked.\n\t\treturn fmt.Errorf(\n\t\t\t\"headscale version %s cannot be used with a database last used by %s, \"+\n\t\t\t\t\"downgrading to a previous minor version is not supported, \"+\n\t\t\t\t\"release page: https://github.com/juanfont/headscale/releases: %w\",\n\t\t\tcurrentVersion, storedVersion,\n\t\t\terrVersionDowngrade,\n\t\t)\n\t}\n}\n","sourceCodeStart":253,"sourceCodeEnd":280,"githubUrl":"https://github.com/juanfont/headscale/blob/565fd254d06c4c7f9a8cad1714a43445c79ba420/hscontrol/db/versioncheck.go#L253-L280","documentation":"The version check found the database was last written by a NEWER minor version than the running binary (minorDiff < 0). Downgrades are blocked because newer migrations may have introduced schema the old binary cannot understand. The sentinel errVersionDowngrade is wrapped for detection.","triggerScenarios":"Rolling back headscale to an older minor release (e.g. v0.26 binary against a v0.27 database), or a container image pin reverted while the data volume kept its newer schema.","commonSituations":"Attempted rollback after a bad upgrade; CI using an older image against a shared persistent database; accidentally running an old binary installed system-wide while a newer one created the DB.","solutions":["Upgrade the binary back to at least the version that last wrote the database (version shown in the message).","If a rollback is truly required, restore the database from a backup taken before the upgrade — schema-level downgrade is not supported.","For disposable environments, delete/recreate the database and re-register nodes."],"exampleFix":null,"handlingStrategy":"fallback","validationCode":null,"typeGuard":null,"tryCatchPattern":"if errors.Is(err, errVersionDowngrade) {\n    // roll forward: run the newer binary that matches the DB,\n    // or restore the pre-upgrade backup — no schema downgrade exists\n}","preventionTips":["Always back up the database immediately before upgrades so rollback is possible.","Pin container image tags; avoid reverting to older minors against newer data volumes.","Verify 'headscale version' matches the version that last wrote the DB before downgrades."],"tags":["versioning","database","migration","downgrade","startup"],"backgroundTag":null,"analyzedSha":"565fd254d06c4c7f9a8cad1714a43445c79ba420","analyzedAt":"2026-08-15T13:12:30.133Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}