{"record":{"id":"cd1b6fe053cf35d6","repo":"k3s-io/k3s","slug":"vpn-error-tailscale-requires-a-joinkey","errorCode":null,"errorMessage":"VPN Error. Tailscale requires a JoinKey","messagePattern":"VPN Error\\. Tailscale requires a JoinKey","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/vpn/vpn.go","lineNumber":146,"sourceCode":"\t\t\tauthInfo.JoinKey = vpnKeyValue[1]\n\t\tcase \"controlServerURL\":\n\t\t\tauthInfo.ControlServerURL = vpnKeyValue[1]\n\t\tdefault:\n\t\t\treturn vpnCliAuthInfo{}, fmt.Errorf(\"VPN Error. The passed VPN auth info includes an unknown parameter: %v\", vpnKeyValue[0])\n\t\t}\n\t}\n\n\tif err := isVPNConfigOK(authInfo); err != nil {\n\t\treturn authInfo, err\n\t}\n\treturn authInfo, nil\n}\n\n// isVPNConfigOK checks that the config is complete\nfunc isVPNConfigOK(authInfo vpnCliAuthInfo) error {\n\tif authInfo.Name == \"tailscale\" {\n\t\tif authInfo.JoinKey == \"\" {\n\t\t\treturn errors.New(\"VPN Error. Tailscale requires a JoinKey\")\n\t\t}\n\t\tif authInfo.ControlServerURL != \"\" {\n\t\t\tif _, err := url.Parse(authInfo.ControlServerURL); err != nil {\n\t\t\t\treturn fmt.Errorf(\"VPN Error. Invalid control server URL for Tailscale: %w\", err)\n\t\t\t}\n\t\t}\n\t\treturn nil\n\t}\n\n\treturn errors.New(\"Requested VPN: \" + authInfo.Name + \" is not supported. We currently only support tailscale\")\n}\n\n// getTailscaleInfo returns the IPs of the interface\nfunc getTailscaleInfo() (*Info, error) {\n\toutput, err := util.ExecCommand(\"tailscale\", []string{\"status\", \"--json\"})\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to run tailscale status --json: %v\", err)\n\t}","sourceCodeStart":128,"sourceCodeEnd":164,"githubUrl":"https://github.com/k3s-io/k3s/blob/6ba341e396edc16b8dcae978a7c5e3ac7ee5606e/pkg/vpn/vpn.go#L128-L164","documentation":"isVPNConfigOK validates the vpnCliAuthInfo parsed from the --vpn-auth flag string (comma-separated key=value pairs: name, joinKey, controlServerURL). For name=tailscale a non-empty joinKey is mandatory — the agent later runs 'tailscale up --authkey <joinKey> --timeout=30s' — so an empty JoinKey fails here before tailscale is ever invoked.","triggerScenarios":"--vpn-auth=\"name=tailscale\" with no joinKey entry (or joinKey= with an empty value, e.g. an unset env var interpolated into the flag), typically together with --flannel-backend=tailscale.","commonSituations":"Enabling the tailscale flannel backend but forgetting the auth key; flag templates that drop the key; joinKey=${TS_KEY} with the variable unset (yields 'joinKey=' which splits to empty).","solutions":["Add the key: --vpn-auth=\"name=tailscale,joinKey=tskey-auth-xxxxxxxx\"","Create a (reusable) auth key in the Tailscale admin console (or Headscale) first","If a custom coordination server is used, keep controlServerURL well-formed as well, e.g. name=tailscale,joinKey=...,controlServerURL=https://headscale.example"],"exampleFix":"# before\n--vpn-auth=\"name=tailscale\"\n\n# after\n--vpn-auth=\"name=tailscale,joinKey=tskey-auth-abcdef123456\"","handlingStrategy":"validation","validationCode":"func validVPNAuth(s string) bool {\n    kv := map[string]string{}\n    for _, p := range strings.Split(s, \",\") {\n        parts := strings.SplitN(p, \"=\", 2)\n        if len(parts) != 2 {\n            return false\n        }\n        kv[parts[0]] = parts[1]\n    }\n    return kv[\"name\"] == \"tailscale\" && kv[\"joinKey\"] != \"\"\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Generate the auth key before enabling the tailscale backend","Fail deployment templates when the join key variable is empty instead of rendering 'joinKey='","Remember the accepted keys: name, joinKey, controlServerURL — anything else is rejected as unknown"],"tags":["vpn","tailscale","flannel","config","auth"],"backgroundTag":null,"analyzedSha":"6ba341e396edc16b8dcae978a7c5e3ac7ee5606e","analyzedAt":"2026-08-15T16:27:54.286Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}