nats-io/nats-server · error

filter by subject only valid with account filtering

Error message

filter by subject only valid with account filtering

What it means

Connz rejects FilterSubject when no account filter is set. Subject-based connection filtering is implemented against a single account's subscription tree, so it is only valid in combination with an accounts filter.

Source

Thrown at server/monitor.go:266

		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,
		Now:    time.Now().UTC(),
	}

	// Open clients
	var openClients []*client
	// Hold for closed clients if requested.
	var closedClients []*closedClient

	var clist map[uint64]*client

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Add an account scope: Connz(&ConnzOptions{Accounts: []string{"ACC"}, FilterSubject: "foo.bar"})
2. Remove FilterSubject if you genuinely want all accounts
3. On the HTTP endpoint use /connz?acc=ACC&filter_subject=foo.bar

Example fix

// before
connz, err := s.Connz(&server.ConnzOptions{FilterSubject: "foo.bar"})
// after
connz, err := s.Connz(&server.ConnzOptions{Accounts: []string{"A"}, FilterSubject: "foo.bar"})

func validConnzFilter(o *server.ConnzOptions) bool {
	return o.FilterSubject == "" || len(o.Accounts) == 1 || o.Account != ""
}

cz, err := srv.Connz(opts)
if err != nil && strings.Contains(err.Error(), "filter by subject only valid") {
	return nil, fmt.Errorf("FilterSubject requires an account filter: %w", err)
}

When it happens

Trigger: Calling Connz with ConnzOptions.FilterSubject set while opts.Account (and the accounts list) is empty; requesting /connz?filter_subject=foo without an acc parameter.

Common situations: Building dashboards that filter connections by subscribed subject; forgetting that subject filtering requires scoping to one account; copy-pasting options from Subsz examples into Connz.

Related errors

• sort by reason only valid on closed connections
• 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/c931fffa0c63db59. Report an issue: GitHub.