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

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
• leafnodes disabled
• remote leafnode has same cluster name
• 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.

Appendix: 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)