nats-io/nats-server · error

remote leafnode has same cluster name

Error message

remote leafnode has same cluster name

What it means

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).

Source

Thrown at server/errors.go:91

	// ErrTooManySubs signals a client that the maximum number of subscriptions per connection
	// has been reached.
	ErrTooManySubs = errors.New("maximum subscriptions exceeded")

	// ErrTooManySubTokens signals a client that the subject has too many tokens.
	ErrTooManySubTokens = errors.New("subject has exceeded number of tokens limit")

	// ErrClientConnectedToRoutePort represents an error condition when a client
	// attempted to connect to the route listen port.
	ErrClientConnectedToRoutePort = errors.New("attempted to connect to route port")

	// ErrClientConnectedToLeafNodePort represents an error condition when a client
	// attempted to connect to the leaf node listen port.
	ErrClientConnectedToLeafNodePort = errors.New("attempted to connect to leaf node port")

	// ErrLeafNodeHasSameClusterName represents an error condition when a leafnode is a cluster
	// and it has the same cluster name as the hub cluster.
	ErrLeafNodeHasSameClusterName = errors.New("remote leafnode has same cluster name")

	// ErrLeafNodeDisabled is when we disable leafnodes.
	ErrLeafNodeDisabled = errors.New("leafnodes disabled")

	// ErrConnectedToWrongPort represents an error condition when a connection is attempted
	// to the wrong listen port (for instance a LeafNode to a client port, etc...)
	ErrConnectedToWrongPort = errors.New("attempted to connect to wrong port")

	// ErrAccountExists is returned when an account is attempted to be registered
	// but already exists.
	ErrAccountExists = errors.New("account exists")

	// ErrBadAccount represents a malformed or incorrect account.
	ErrBadAccount = errors.New("bad account")

	// ErrReservedAccount represents a reserved account that can not be created.
	ErrReservedAccount = errors.New("reserved account")

View on GitHub (pinned to 3a66a489d2)

Solutions

  1. Change the remote server's cluster.name to a unique value distinct from the hub's
  2. Review all leaf-remotes' configs to guarantee globally unique cluster names
  3. Restart the remote leaf server so the new cluster name is announced

Example fix

// before (remote.conf)
cluster { name: "prod" }
leafnodes { remotes: [ { url: "nats://hub:7422" } ] }
// after
cluster { name: "staging" }
leafnodes { remotes: [ { url: "nats://hub:7422" } ] }
Defensive patterns

Strategy: validation

Validate before calling

// before connecting a leaf remote, assert distinct cluster names
if remoteClusterName == hubClusterName {
    return fmt.Errorf("remote cluster name %q must differ from hub %q", remoteClusterName, hubClusterName)
}

Try / catch

if err := tryLeafConnect(); err != nil && strings.Contains(err.Error(), "same cluster name") {
    log.Fatalf("fix remote cluster.name: %v", err)
}

Prevention

When it happens

Trigger: 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().

Common situations: 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.

Related errors

AI-assisted analysis of nats-io/nats-server@3a66a489d2 (2026-09-02). Data as JSON: /api/errors/f70e2c03c4ab92e7. Report an issue: GitHub.