{"record":{"id":"f70e2c03c4ab92e7","repo":"nats-io/nats-server","slug":"remote-leafnode-has-same-cluster-name","errorCode":null,"errorMessage":"remote leafnode has same cluster name","messagePattern":"remote leafnode has same cluster name","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"server/errors.go","lineNumber":91,"sourceCode":"\n\t// ErrTooManySubs signals a client that the maximum number of subscriptions per connection\n\t// has been reached.\n\tErrTooManySubs = errors.New(\"maximum subscriptions exceeded\")\n\n\t// ErrTooManySubTokens signals a client that the subject has too many tokens.\n\tErrTooManySubTokens = errors.New(\"subject has exceeded number of tokens limit\")\n\n\t// ErrClientConnectedToRoutePort represents an error condition when a client\n\t// attempted to connect to the route listen port.\n\tErrClientConnectedToRoutePort = errors.New(\"attempted to connect to route port\")\n\n\t// ErrClientConnectedToLeafNodePort represents an error condition when a client\n\t// attempted to connect to the leaf node listen port.\n\tErrClientConnectedToLeafNodePort = errors.New(\"attempted to connect to leaf node port\")\n\n\t// ErrLeafNodeHasSameClusterName represents an error condition when a leafnode is a cluster\n\t// and it has the same cluster name as the hub cluster.\n\tErrLeafNodeHasSameClusterName = errors.New(\"remote leafnode has same cluster name\")\n\n\t// ErrLeafNodeDisabled is when we disable leafnodes.\n\tErrLeafNodeDisabled = errors.New(\"leafnodes disabled\")\n\n\t// ErrConnectedToWrongPort represents an error condition when a connection is attempted\n\t// to the wrong listen port (for instance a LeafNode to a client port, etc...)\n\tErrConnectedToWrongPort = errors.New(\"attempted to connect to wrong port\")\n\n\t// ErrAccountExists is returned when an account is attempted to be registered\n\t// but already exists.\n\tErrAccountExists = errors.New(\"account exists\")\n\n\t// ErrBadAccount represents a malformed or incorrect account.\n\tErrBadAccount = errors.New(\"bad account\")\n\n\t// ErrReservedAccount represents a reserved account that can not be created.\n\tErrReservedAccount = errors.New(\"reserved account\")\n","sourceCodeStart":73,"sourceCodeEnd":109,"githubUrl":"https://github.com/nats-io/nats-server/blob/3a66a489d262bf89b71a71c955c94920394532f3/server/errors.go#L73-L109","documentation":"ErrLeafNodeHasSameClusterName is returned when a solicited leaf-node connection announces a cluster name identical to the accepting server's own cluster name. Two distinct clusters must not share a name when connected via leaf nodes, as it would create ambiguous routing and cluster identity; the server rejects the leaf connect with ClusterNamesIdentical (leafnode.go:2251).","triggerScenarios":"A remote NATS server configured with leafnodes remotes connects to a hub whose cluster name equals the remote's own 'cluster.name'. Detected in leaf CONNECT processing when proto.Cluster == s.cachedClusterName().","commonSituations":"Copying the same server config to multiple machines so both have cluster { name: \"cluster-A\" } while one leaf-connects to the other; staging cluster connecting to production hub with identical names; template rendering leaving the default cluster name unchanged on both sides.","solutions":["Change the remote server's cluster.name to a unique value distinct from the hub's","Review all leaf-remotes' configs to guarantee globally unique cluster names","Restart the remote leaf server so the new cluster name is announced"],"exampleFix":"// before (remote.conf)\ncluster { name: \"prod\" }\nleafnodes { remotes: [ { url: \"nats://hub:7422\" } ] }\n// after\ncluster { name: \"staging\" }\nleafnodes { remotes: [ { url: \"nats://hub:7422\" } ] }","handlingStrategy":"validation","validationCode":"// before connecting a leaf remote, assert distinct cluster names\nif remoteClusterName == hubClusterName {\n    return fmt.Errorf(\"remote cluster name %q must differ from hub %q\", remoteClusterName, hubClusterName)\n}","typeGuard":null,"tryCatchPattern":"if err := tryLeafConnect(); err != nil && strings.Contains(err.Error(), \"same cluster name\") {\n    log.Fatalf(\"fix remote cluster.name: %v\", err)\n}","preventionTips":["Keep an inventory of cluster names across environments","Generate cluster.name per environment in config templates","Avoid copying one server's full config to another node unchanged"],"tags":["nats","leafnode","cluster","configuration"],"backgroundTag":"cluster-name-collision","analyzedSha":"3a66a489d262bf89b71a71c955c94920394532f3","analyzedAt":"2026-09-02T04:41:54.247Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}