juanfont/headscale · error · ErrUnsupportedClientVersion

unsupported client version: %s (%d)

Error message

unsupported client version: %s (%d)

What it means

Error "unsupported client version: %s (%d)" thrown in juanfont/headscale.

Source

Thrown at hscontrol/noise.go:286

func rejectUnsupported(
	writer http.ResponseWriter,
	version tailcfg.CapabilityVersion,
	mkey key.MachinePublic,
	nkey key.NodePublic,
) bool {
	// Reject unsupported versions
	if !isSupportedVersion(version) {
		log.Error().
			Caller().
			Int("minimum_cap_ver", int(capver.MinSupportedCapabilityVersion)).
			Int("client_cap_ver", int(version)).
			Str("minimum_version", capver.TailscaleVersion(capver.MinSupportedCapabilityVersion)).
			Str("client_version", capver.TailscaleVersion(version)).
			Str("node.key", nkey.ShortString()).
			Str("machine.key", mkey.ShortString()).
			Msg("unsupported client connected")
		http.Error(writer, unsupportedClientError(version).Error(), http.StatusBadRequest)

		return true
	}

	return false
}

// overrideRemoteAddr returns middleware that pins r.RemoteAddr to addr.
// Used inside the Noise tunnel: the HTTP/2 server derives r.RemoteAddr
// from the hijacked TCP socket (the reverse proxy's loopback peer), so
// the outer request's resolved client IP must be carried across the
// hijack boundary by hand.
func overrideRemoteAddr(addr string) func(http.Handler) http.Handler {
	return func(next http.Handler) http.Handler {
		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
			r.RemoteAddr = addr
			next.ServeHTTP(w, r)
		})

View on GitHub (pinned to 565fd254d0)

Solutions

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

When it happens

Trigger: Thrown at hscontrol/noise.go:286 when the library encounters an invalid state.

Common situations: The Tailscale client's capability version is unsupported by this headscale build. Upgrade the client or check capver compatibility.

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