What causes "attempted to connect to route port" in nats-io/nats-server?

Point the client at the client listen port (the 'port' or default 4222), not the route port (default 6222)

attempted to connect to route port

Error message

attempted to connect to route port

What it means

ErrClientConnectedToRoutePort indicates a client (which provided a 'lang' field in its CONNECT protocol) attempted to connect to the NATS cluster route listen port instead of the client port. ROUTE connections never send lang in CONNECT, so its presence identifies the connection as a normal client library connection to the wrong port. The server sends the error and closes the connection with WrongPort.

Source

Thrown at server/errors.go:83

	ErrTooManyConnections = errors.New("maximum connections exceeded")

	// ErrTooManyAccountConnections signals that an account has reached its maximum number of active
	// connections.
	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.

View on GitHub (pinned to 3a66a489d2)

Solutions

Point the client at the client listen port (the 'port' or default 4222), not the route port (default 6222)
Check the server config to confirm which port is 'port' vs 'cluster { port }'
Verify with environment/deployment config that the URL given to nats.Connect was not templated from the route address

Example fix

// before
nc, err := nats.Connect("nats://nats-1:6222") // route port
// after
nc, err := nats.Connect("nats://nats-1:4222") // client port

Defensive patterns

Strategy: validation

Validate before calling

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

Type guard

func isLikelyClientURL(natsURL string) bool {
    u, err := url.Parse(natsURL)
    return err == nil && u.Port() != "6222" && u.Port() != "7422"
}

Try / catch

nc, err := nats.Connect(url)
if err != nil && strings.Contains(err.Error(), "route port") {
    log.Fatalf("wrong port in %q: use the client listen port", url)
}

Prevention

Never copy cluster route URLs into client configuration
Name config variables explicitly (NATS_CLIENT_URL vs NATS_ROUTE_URL)
Verify ports against the server config after topology changes

When it happens

Trigger: Pointing a NATS client library (Go, Java, etc.) at nats://host:ROUTE_PORT. Specifically in route.go:3054, during route CONNECT processing, if the lang field is non-empty the server treats the connection as a client and returns this error.

Common situations: Configuration mistake: using the cluster/route port (e.g. 6222) instead of the client port (e.g. 4222) in the client's servers URL; copying the route URL from a cluster config into application config; port swaps after a config refactor.

Related errors

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