nats-io/nats-server · error

sort by reason only valid on closed connections

Error message

sort by reason only valid on closed connections

What it means

Connz returns this when you request sorting by ByReason (or ByStop) while the state filter is not ConnClosed. Stop time and close reason are only recorded for closed connections, so sorting on them for open/all connections is meaningless and rejected.

Source

Thrown at server/monitor.go:256

		subsDet = opts.SubscriptionsDetail
		offset = opts.Offset
		if offset < 0 {
			offset = 0
		}
		limit = opts.Limit
		if limit <= 0 {
			limit = DefaultConnListSize
		}
		// state
		state = opts.State

		// ByStop only makes sense on closed connections
		if sortOpt == ByStop && state != ConnClosed {
			return nil, fmt.Errorf("sort by stop only valid on closed connections")
		}
		// ByReason is the same.
		if sortOpt == ByReason && state != ConnClosed {
			return nil, fmt.Errorf("sort by reason only valid on closed connections")
		}
		// If searching by CID
		if opts.CID > 0 {
			cid = opts.CID
			limit = 1
		}
		// If filtering by subject.
		if opts.FilterSubject != _EMPTY_ && opts.FilterSubject != fwcs {
			if acc == _EMPTY_ {
				return nil, fmt.Errorf("filter by subject only valid with account filtering")
			}
			filter = opts.FilterSubject
		}
	}

	c := &Connz{
		Offset: offset,
		Limit:  limit,

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Pass ByClosed (ConnClosed) state together with ByReason: Connz(&ConnzOptions{State: ConnClosed, SortOpt: ByReason})
2. If you need open connections, drop the ByReason sort and use the default sort instead
3. On the HTTP endpoint, request /connz?state=closed&sort=reason

Example fix

// before
connz, err := s.Connz(&server.ConnzOptions{SortOpt: server.ByReason})
// after
connz, err := s.Connz(&server.ConnzOptions{State: server.ConnClosed, SortOpt: server.ByReason})

func validConnzOpts(o *server.ConnzOptions) bool {
	if o.SortOpt == server.ByReason || o.SortOpt == server.ByStop {
		return o.State == server.ConnClosed
	}
	return true
}

cz, err := srv.Connz(opts)
if err != nil {
	if strings.Contains(err.Error(), "only valid on closed connections") {
		opts.State = server.ConnClosed
		cz, err = srv.Connz(opts)
	}
}

When it happens

Trigger: Calling Connz with SortOpt=ByReason (or ByStop) while opts.State is ConnAll, ConnOpen, or left unset; hitting the /connz monitoring endpoint with sort=reason but without state=closed.

Common situations: Building monitoring dashboards that list connection disconnect reasons; after upgrading the nats-server monitoring API and enabling the newer ByReason sort; testing monitor endpoints (TestMonitorConnzSortedByReasonOnOpen exercises exactly this rejection).

Related errors

• filter by subject only valid with account filtering
• fetching jwt failed due to shutdown
• fetching jwt timed out
• subject %q is malformed
• Error decoding state for %s

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