{"record":{"id":"a937e3accdd623a6","repo":"juanfont/headscale","slug":"errunsupportedclientversion","errorCode":"ErrUnsupportedClientVersion","errorMessage":"unsupported client version: %s (%d)","messagePattern":"unsupported client version: (.+?) \\((.+?)\\)","errorType":"http","errorClass":null,"httpStatus":400,"severity":"warning","filePath":"hscontrol/noise.go","lineNumber":225,"sourceCode":"\t\tr.Post(\"/c2n\", ns.NotImplementedHandler)\n\t})\n\n\tns.httpBaseConfig = &http.Server{\n\t\tHandler:           r,\n\t\tReadHeaderTimeout: types.HTTPTimeout,\n\t}\n\tns.http2Server = &http2.Server{}\n\n\tns.http2Server.ServeConn(\n\t\tnoiseConn,\n\t\t&http2.ServeConnOpts{\n\t\t\tBaseConfig: ns.httpBaseConfig,\n\t\t},\n\t)\n}\n\nfunc unsupportedClientError(version tailcfg.CapabilityVersion) error {\n\treturn fmt.Errorf(\"%w: %s (%d)\", ErrUnsupportedClientVersion, capver.TailscaleVersion(version), version)\n}\n\nfunc (ns *noiseServer) earlyNoise(protocolVersion int, writer io.Writer) error {\n\tif !isSupportedVersion(tailcfg.CapabilityVersion(protocolVersion)) {\n\t\treturn unsupportedClientError(tailcfg.CapabilityVersion(protocolVersion))\n\t}\n\n\tearlyJSON, err := json.Marshal(&tailcfg.EarlyNoise{\n\t\tNodeKeyChallenge: ns.challenge.Public(),\n\t})\n\tif err != nil {\n\t\treturn err\n\t}\n\n\t// 5 bytes that won't be mistaken for an HTTP/2 frame:\n\t// https://httpwg.org/specs/rfc7540.html#rfc.section.4.1 (Especially not\n\t// an HTTP/2 settings frame, which isn't of type 'T')\n\tvar notH2Frame [5]byte","sourceCodeStart":207,"sourceCodeEnd":243,"githubUrl":"https://github.com/juanfont/headscale/blob/565fd254d06c4c7f9a8cad1714a43445c79ba420/hscontrol/noise.go#L207-L243","documentation":"Returned during the early Noise stage when the client's declared protocol/capability version is below the minimum supported by this headscale build (isSupportedVersion check against capver data). The error names the mapped Tailscale version and raw capability number via ErrUnsupportedClientVersion.","triggerScenarios":"A tailscaled older than the server's minimum supported capability version connects via /ts2021; earlyNoise rejects it before any API traffic flows.","commonSituations":"Distro-packaged stale tailscale clients (e.g. 1.32-era) against a current headscale; embedded appliances that rarely update; after a headscale upgrade that raised the minimum capver.","solutions":["Upgrade the client tailscaled to a recent stable release (check the version in the error message)","Compare the client's capability version against hscontrol/capver data to find the minimum accepted","If upgrading is impossible, pin an older headscale release that still supports that capability version"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"if !isSupportedVersion(clientCapVer) {\n    return fmt.Errorf(\"client version %s (%d) is below minimum supported; upgrade tailscaled\",\n        capver.TailscaleVersion(clientCapVer), clientCapVer)\n}","typeGuard":"func isSupportedClient(v tailcfg.CapabilityVersion) bool {\n    return isSupportedVersion(v)\n}","tryCatchPattern":null,"preventionTips":["Pin client tailscaled versions at or above headscale's minimum capability version in fleet management","Monitor for ErrUnsupportedClientVersion in logs to catch stale clients before they multiply"],"tags":["version-compat","noise","capability-version","upgrade"],"backgroundTag":null,"analyzedSha":"565fd254d06c4c7f9a8cad1714a43445c79ba420","analyzedAt":"2026-08-15T13:12:30.133Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}