{"record":{"id":"ecd2212e3168bbae","repo":"k3s-io/k3s","slug":"invalid-node-ip-address-s","errorCode":null,"errorMessage":"invalid node IP address %s","messagePattern":"invalid node IP address (.+?)","errorType":"http","errorClass":null,"httpStatus":500,"severity":"error","filePath":"pkg/server/handlers/handlers.go","lineNumber":75,"sourceCode":"\t\tresp.Header().Set(\"Content-Length\", strconv.Itoa(len(data)))\n\t\tresp.Write(data)\n\t})\n}\n\nfunc ServingKubeletCert(control *config.Control, auth nodepassword.NodeAuthValidator) http.Handler {\n\treturn http.HandlerFunc(func(resp http.ResponseWriter, req *http.Request) {\n\t\tnodeName, errCode, err := auth(req)\n\t\tif err != nil {\n\t\t\tutil.SendError(err, resp, req, errCode)\n\t\t\treturn\n\t\t}\n\n\t\tips := []net.IP{net.ParseIP(\"127.0.0.1\"), net.ParseIP(\"::1\")}\n\t\tif nodeIP := req.Header.Get(version.Program + \"-Node-IP\"); nodeIP != \"\" {\n\t\t\tfor _, v := range strings.Split(nodeIP, \",\") {\n\t\t\t\tip := net.ParseIP(v)\n\t\t\t\tif ip == nil {\n\t\t\t\t\tutil.SendError(fmt.Errorf(\"invalid node IP address %s\", ip), resp, req)\n\t\t\t\t\treturn\n\t\t\t\t}\n\t\t\t\tips = append(ips, ip)\n\t\t\t}\n\t\t}\n\n\t\tsignAndSend(resp, req, control.Runtime.ServerCA, control.Runtime.ServerCAKey, control.Runtime.ServingKubeletKey, certutil.Config{\n\t\t\tCommonName: nodeName,\n\t\t\tUsages:     []x509.ExtKeyUsage{x509.ExtKeyUsageServerAuth},\n\t\t\tAltNames: certutil.AltNames{\n\t\t\t\tDNSNames: []string{nodeName, \"localhost\"},\n\t\t\t\tIPs:      ips,\n\t\t\t},\n\t\t})\n\t})\n}\n\nfunc ClientKubeletCert(control *config.Control, auth nodepassword.NodeAuthValidator) http.Handler {","sourceCodeStart":57,"sourceCodeEnd":93,"githubUrl":"https://github.com/k3s-io/k3s/blob/6ba341e396edc16b8dcae978a7c5e3ac7ee5606e/pkg/server/handlers/handlers.go#L57-L93","documentation":"The kubelet serving-cert signing endpoint (pkg/server/handlers/handlers.go) authenticates the requesting node and builds a SAN list from the k3s-Node-IP request header (comma-separated). Each comma-separated value must parse with net.ParseIP; any unparseable value produces this 400 error before a cert is signed. Note the message formats the already-nil parsed value, so it renders as 'invalid node IP address <nil>' rather than showing the bad input.","triggerScenarios":"An agent (or direct HTTP caller) hits /v1-k3s/serving-kubelet-cert with a k3s-Node-IP header containing a value that net.ParseIP rejects: a hostname, a value with whitespace or a port (e.g. 10.0.0.1:10250), an IPv6 with brackets, or an empty string produced by a trailing/duplicated comma.","commonSituations":"Setting --node-ip with a DNS name or malformed address on k3s agent; shell quoting that appends a stray comma ('--node-ip 10.0.0.1,'); scripts templating the flag from an empty variable; IPv6 addresses passed with surrounding brackets because they came from a URL.","solutions":["Inspect the agent's flags and correct --node-ip to literal IP addresses only (valid IPv4 or IPv6), no hostnames, ports, brackets, or empty segments.","If multiple IPs are needed, keep the comma list strict: exactly one address per element, no trailing comma or spaces.","Restart the k3s agent so it re-registers with the fixed header.","If templating from config management, assert the value matches an IP regex before deploying."],"exampleFix":"# before\nk3s agent --server https://server:6443 --node-ip mynode.example.com,\n\n# after\nk3s agent --server https://server:6443 --node-ip 10.0.0.5","handlingStrategy":"validation","validationCode":"// Agent-side: validate --node-ip before k3s uses it\nfor _, s := range strings.Split(nodeIPFlag, \",\") {\n    if net.ParseIP(strings.TrimSpace(s)) == nil {\n        log.Fatalf(\"invalid --node-ip value %q\", s)\n    }\n}","typeGuard":"func validNodeIPList(v string) bool {\n    if v == \"\" { return true }\n    for _, s := range strings.Split(v, \",\") {\n        if net.ParseIP(s) == nil { return false }\n    }\n    return true\n}","tryCatchPattern":null,"preventionTips":["Pass only literal IPs (no hostnames, ports, brackets) to --node-ip","Lint templated agent configs that interpolate node IP variables","Avoid trailing commas and whitespace in multi-IP lists"],"tags":["network","kubelet","tls","agent"],"backgroundTag":null,"analyzedSha":"6ba341e396edc16b8dcae978a7c5e3ac7ee5606e","analyzedAt":"2026-08-15T16:27:54.286Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}