{"record":{"id":"8d611a356bd4736b","repo":"k3s-io/k3s","slug":"server-node-name-not-set","errorCode":null,"errorMessage":"server node name not set","messagePattern":"server node name not set","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"pkg/etcd/etcd.go","lineNumber":714,"sourceCode":"\t}\n\n\treturn e.handler(handler), nil\n}\n\n// setName sets a unique name for this cluster member. The first time this is called,\n// or if force is set to true, a new name will be generated and written to disk. The persistent\n// name is used on subsequent calls.\nfunc (e *ETCD) setName(force bool) error {\n\t// don't create the name file if etcd is disabled\n\tif e.config.DisableETCD {\n\t\treturn nil\n\t}\n\n\tfileName := nameFile(e.config)\n\tdata, err := os.ReadFile(fileName)\n\tif os.IsNotExist(err) || force {\n\t\tif e.config.ServerNodeName == \"\" {\n\t\t\treturn errors.New(\"server node name not set\")\n\t\t}\n\t\te.name = e.config.ServerNodeName + \"-\" + uuid.New().String()[:8]\n\t\tif err := os.MkdirAll(filepath.Dir(fileName), 0700); err != nil {\n\t\t\treturn err\n\t\t}\n\t\treturn os.WriteFile(fileName, []byte(e.name), 0600)\n\t} else if err != nil {\n\t\treturn err\n\t}\n\te.name = string(data)\n\treturn nil\n}\n\n// handler wraps the handler with routes for database info\nfunc (e *ETCD) handler(next http.Handler) http.Handler {\n\tr := mux.NewRouter()\n\tr.NotFoundHandler = next\n","sourceCodeStart":696,"sourceCodeEnd":732,"githubUrl":"https://github.com/k3s-io/k3s/blob/6ba341e396edc16b8dcae978a7c5e3ac7ee5606e/pkg/etcd/etcd.go#L696-L732","documentation":"setName persists an etcd member name '<ServerNodeName>-<uuid8>' in a file; when the file is missing or force=true (fresh cluster / cluster-reset), it needs ServerNodeName to build that name. Empty ServerNodeName (normally defaulted from the hostname) makes member naming impossible.","triggerScenarios":"os.Hostname() returning an empty string (broken container/VM hostname); config explicitly setting an empty node-name; running with a stripped environment where hostname resolution fails.","commonSituations":"Containers started with --hostname '' or a misconfigured runtime; minimal chroots; automated environments where hostname was unset.","solutions":["Set a hostname on the host/container (hostnamectl or --hostname on docker run).","Or pass the name explicitly: k3s server --node-name <unique-name> (K3S_NODE_NAME).","Restart k3s; setName will write the name file and continue."],"exampleFix":"# before: empty hostname\n$ hostname\n(empty)\n# after\nhostnamectl set-hostname node-a   # or: k3s server --node-name node-a","handlingStrategy":"validation","validationCode":"// Pre-flight the node name before k3s start:\nfunc nodeNameSet(cfg Config) error {\n\tif cfg.ServerNodeName == \"\" {\n\t\thn, err := os.Hostname()\n\t\tif err != nil || hn == \"\" {\n\t\t\treturn errors.New(\"no node name: set hostname or pass --node-name\")\n\t\t}\n\t}\n\treturn nil\n}","typeGuard":null,"tryCatchPattern":"if err := e.setName(true); err != nil {\n\tif strings.Contains(err.Error(), \"server node name not set\") {\n\t\t// provision hostname or --node-name, then retry start\n\t}\n}","preventionTips":["Always set an explicit hostname or --node-name in node provisioning (cloud-init, ignition, docker --hostname).","Include a hostname check in node bootstrap scripts for containers and minimal VMs.","Keep the etcd name file intact: deleting it forces regeneration, which then requires a node name."],"tags":["k3s","etcd","node-name","hostname","startup"],"backgroundTag":null,"analyzedSha":"6ba341e396edc16b8dcae978a7c5e3ac7ee5606e","analyzedAt":"2026-08-15T16:27:54.286Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}