juanfont/headscale · critical · errVersionDowngrade

headscale version %s cannot be used with a database last use

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.

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)

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

• version check: %w
• headscale version %s cannot be used with a database last use
• headscale version %s cannot be used with a database last use
• automigrating types.Route: %w
• checking if table %s exists: %w

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