nats-io/nats-server · error

attempted to connect to leaf node port

Error message

attempted to connect to leaf node port

What it means

ErrClientConnectedToLeafNodePort means a regular client connection attempted to connect to the leaf-node listen port. The leafnode CONNECT handshake carries no 'lang' field, so when a connection supplies lang the server knows it is a client library and not a leaf node, sends the error, and closes with WrongPort (leafnode.go:2226).

Source

Thrown at server/errors.go:87

	ErrTooManyAccountConnections = errors.New("maximum account active connections exceeded")

	// ErrLeafNodeLoop signals a leafnode is trying to register for a cluster we already have registered.
	ErrLeafNodeLoop = errors.New("leafnode loop detected")

	// 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")

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Point the client at the client port (default 4222), not the leafnodes port (default 7422)
2. Check server config under 'leafnodes { listen }' to identify the leaf port and avoid it in client URLs
3. If a leaf node connection is intended, use a server that speaks the leaf protocol (another NATS server), not a client library

Example fix

// before
nc, _ := nats.Connect("nats://nats-1:7422") // leafnode port
// after
nc, _ := nats.Connect("nats://nats-1:4222") // client port

u, err := url.Parse(natsURL)
if err != nil { return err }
if port := u.Port(); port == "7422" { return fmt.Errorf("%s is a leafnode port; use the client port", natsURL) }

func isClientPort(u *url.URL) bool { return u.Port() != "7422" && u.Port() != "6222" }

nc, err := nats.Connect(url)
if err != nil && strings.Contains(err.Error(), "leaf node port") {
    log.Fatalf("%q points at the leafnode port; use the client port", url)
}

When it happens

Trigger: Connecting a normal NATS client (which sends lang in CONNECT) to the leafnodes listen port, e.g. nats://host:7422 when 7422 is the leafnode port. Triggered during leaf CONNECT processing when lang != "".

Common situations: Using the leafnode port in an application's client URL; confusing leafnode port with client port after deploying gateways/superclusters; docker service exposing multiple ports where the wrong one is mapped in the client config.

Related errors

• attempted to connect to wrong port
• attempted to connect to route port
• remote leafnode has same cluster name
• leafnodes disabled
• account jwt not found

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