juanfont/headscale · critical · errVersionDowngrade

headscale version cannot be used with a database last used…

Error message

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

What it means

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.

Solutions

1. Upgrade the binary back to at least the version that last wrote the database (version shown in the message).
2. If a rollback is truly required, restore the database from a backup taken before the upgrade — schema-level downgrade is not supported.
3. For disposable environments, delete/recreate the database and re-register nodes.

if errors.Is(err, errVersionDowngrade) {
    // roll forward: run the newer binary that matches the DB,
    // or restore the pre-upgrade backup — no schema downgrade exists
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• headscale version cannot be used with a database last used…
• headscale version cannot be used with a database last used…
• version check
• adding hash column
• adding prefix column

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

Appendix: source

Thrown at hscontrol/db/versioncheck.go:271

		// Single minor version upgrade — allowed.
		return nil

	case minorDiff > 1:
		// Multi-minor upgrade — blocked.
		return fmt.Errorf(
			"headscale version %s cannot be used with a database last used by %s, "+
				"upgrading more than one minor version at a time is not supported, "+
				"please upgrade to the latest v%d.%d.x release first, then to %s, "+
				"release page: https://github.com/juanfont/headscale/releases: %w",
			currentVersion, storedVersion,
			stored.Major, stored.Minor+1,
			current.String(),
			errVersionUpgrade,
		)

	default:
		// minorDiff < 0 — any minor downgrade is blocked.
		return fmt.Errorf(
			"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",
			currentVersion, storedVersion,
			errVersionDowngrade,
		)
	}
}

View on GitHub (pinned to 565fd254d0)