{"record":{"id":"cc2c2409a9ecda77","repo":"k3s-io/k3s","slug":"duplicate-node-name-found-please-use-a-unique-nam","errorCode":null,"errorMessage":"duplicate node name found, please use a unique name for this node","messagePattern":"duplicate node name found, please use a unique name for this node","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"pkg/etcd/etcd.go","lineNumber":620,"sourceCode":"\t\t\t\tcluster = append(cluster, fmt.Sprintf(\"%s=%s\", member.Name, member.PeerURLs[0]))\n\t\t\t}\n\t\t}\n\n\t\t// Try to get the node name from the member name\n\t\tmemberNodeName := member.Name\n\t\tif lastHyphen := strings.LastIndex(member.Name, \"-\"); lastHyphen > 1 {\n\t\t\tmemberNodeName = member.Name[:lastHyphen]\n\t\t}\n\n\t\t// Make sure there's not already a member in the cluster with a duplicate node name\n\t\tif member.Name != e.name && memberNodeName == e.config.ServerNodeName {\n\t\t\t// make sure to remove the name file if a duplicate node name is used, so that we\n\t\t\t// generate a new member name when our node name is fixed.\n\t\t\tnameFile := nameFile(e.config)\n\t\t\tif err := os.Remove(nameFile); err != nil {\n\t\t\t\tlogrus.Errorf(\"Failed to remove etcd name file %s: %v\", nameFile, err)\n\t\t\t}\n\t\t\treturn errors.New(\"duplicate node name found, please use a unique name for this node\")\n\t\t}\n\t}\n\n\tif add {\n\t\tlogrus.Infof(\"Adding member %s=%s to etcd cluster %v\", e.name, e.peerURL(), cluster)\n\t\tif _, err = client.MemberAddAsLearner(clientCtx, []string{e.peerURL()}); err != nil {\n\t\t\tif errors.Is(err, context.DeadlineExceeded) {\n\t\t\t\treturn ErrJoinTimeout\n\t\t\t}\n\t\t\treturn err\n\t\t}\n\t\tcluster = append(cluster, fmt.Sprintf(\"%s=%s\", e.name, e.peerURL()))\n\t\tstate = \"existing\"\n\t} else if len(cluster) > 1 {\n\t\tlogrus.Infof(\"Starting etcd to join cluster with members %v\", cluster)\n\t\tstate = \"existing\"\n\t} else {\n\t\tlogrus.Infof(\"Starting etcd for new cluster\")","sourceCodeStart":602,"sourceCodeEnd":638,"githubUrl":"https://github.com/k3s-io/k3s/blob/6ba341e396edc16b8dcae978a7c5e3ac7ee5606e/pkg/etcd/etcd.go#L602-L638","documentation":"While forming/joining etcd, each existing member name is stripped of its trailing '-<uuid8>' suffix; if the remainder equals this server's ServerNodeName but the full member name differs, another node already joined with the same node name. k3s deletes its own etcd name file (so a corrected name generates a fresh member) and aborts.","triggerScenarios":"Two hosts configured with the same --node-name (or identical hostnames) joining one cluster; cloned VMs retaining hostname; explicit --node-name collisions across environments.","commonSituations":"Cloud images cloned without hostname changes; homogeneous bare-metal named identically by a provisioning system; explicit node-name set to a shared value like 'master'.","solutions":["Give every node a unique hostname or pass a unique --node-name (K3S_NODE_NAME) before restarting k3s.","If the duplicate member is a dead node, remove it (etcdctl member remove / k3s etcd remove-member) and rejoin the fixed node.","Restart k3s on the corrected node; the deleted name file causes a new member identity to be generated."],"exampleFix":"# before: both hosts run\nk3s server --node-name master\n# after: unique names per host\nk3s server --node-name master-a   # host 1\nk3s server --node-name master-b   # host 2","handlingStrategy":"validation","validationCode":"// Before join, verify no existing member shares this node name (ignoring uuid suffix):\nfunc nodeNameFree(members []*etcdserverpb.Member, serverNodeName string) bool {\n\tfor _, m := range members {\n\t\tname := m.Name\n\t\tif i := strings.LastIndex(name, \"-\"); i > 1 { name = name[:i] }\n\t\tif m.Name != ownFullName && name == serverNodeName { return false }\n\t}\n\treturn true\n}","typeGuard":null,"tryCatchPattern":"if err := e.joinCluster(ctx); err != nil {\n\tif strings.Contains(err.Error(), \"duplicate node name found\") {\n\t\t// set unique --node-name on this host and restart; k3s already removed the stale name file\n\t}\n}","preventionTips":["Assign unique hostnames/node-names at provisioning time; assert uniqueness in your CMDB.","For cloned VMs/templates, force a new hostname and machine-id before first k3s start.","Avoid 'master'/'node' style generic names across multi-cluster fleets sharing etcd."],"tags":["k3s","etcd","node-name","join","duplicate"],"backgroundTag":null,"analyzedSha":"6ba341e396edc16b8dcae978a7c5e3ac7ee5606e","analyzedAt":"2026-08-15T16:27:54.286Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}