nats-io/nats-server · error

subject has exceeded number of tokens limit

Error message

subject has exceeded number of tokens limit

What it means

ErrTooManySubTokens means a subscription subject has more tokens (dot-separated segments) than the server's max_subject_tokens limit (or fewer than the minimum). The NATS server enforces this at SUBSCRIBE time to reject subjects that are structurally invalid or suspiciously deep, protecting subject-based routing tables from abuse. It is returned to the client from the SUB/subscription processing path in client.go.

Source

Thrown at server/errors.go:79

	ErrBadClientProtocol = errors.New("invalid client protocol")

	// ErrTooManyConnections signals a client that the maximum number of connections supported by the
	// server has been reached.
	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...)

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Reduce the number of tokens in the subscription subject by flattening or shortening it
2. Raise max_subject_tokens in the server's configuration and reload/restart the server
3. Check the code that builds the subject string for accidental joining of too many segments
4. Validate subject token count client-side before subscribing

Example fix

// before
nc.Subscribe(strings.Join(parts, "."), handler) // parts may be huge
// after
if len(strings.Split(subject, ".")) > 10 { subject = flattenSubject(subject) }
nc.Subscribe(subject, handler)

func subjectTokenCount(subject string) int { return len(strings.Split(subject, ".")) }
if n := subjectTokenCount(subj); n < 1 || n > 10 { return fmt.Errorf("subject %q has %d tokens, exceeds limit", subj, n) }

func isSubjectWithinLimit(subject string, max int) bool {
    return subject != "" && len(strings.Split(subject, ".")) <= max
}

_, err := nc.Subscribe(subj, handler)
if errors.Is(err, nats.ErrBadSubject) || strings.Contains(err.Error(), "tokens limit") {
    // flatten subject or raise server max_subject_tokens
}

When it happens

Trigger: Calling a SUBSCRIBE API (client.subscribe / nc.Subscribe) with a subject whose token count exceeds the server's max_subject_tokens config, e.g. subscribing to 'a.b.c.d.e.f...' with more tokens than allowed. Also triggered when the subject has too few tokens for a wildcard position in some configurations.

Common situations: Mistakenly passing a payload or reply subject with many dot-separated segments as a subscription subject; misconfigured max_subject_tokens (very low value) in server config; generating subjects programmatically by joining user data with dots (e.g. paths) producing excessive tokens.

Related errors

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

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