{"record":{"id":"c931fffa0c63db59","repo":"nats-io/nats-server","slug":"filter-by-subject-only-valid-with-account-filterin","errorCode":null,"errorMessage":"filter by subject only valid with account filtering","messagePattern":"filter by subject only valid with account filtering","errorType":"http","errorClass":null,"httpStatus":400,"severity":"error","filePath":"server/monitor.go","lineNumber":266,"sourceCode":"\t\tstate = opts.State\n\n\t\t// ByStop only makes sense on closed connections\n\t\tif sortOpt == ByStop && state != ConnClosed {\n\t\t\treturn nil, fmt.Errorf(\"sort by stop only valid on closed connections\")\n\t\t}\n\t\t// ByReason is the same.\n\t\tif sortOpt == ByReason && state != ConnClosed {\n\t\t\treturn nil, fmt.Errorf(\"sort by reason only valid on closed connections\")\n\t\t}\n\t\t// If searching by CID\n\t\tif opts.CID > 0 {\n\t\t\tcid = opts.CID\n\t\t\tlimit = 1\n\t\t}\n\t\t// If filtering by subject.\n\t\tif opts.FilterSubject != _EMPTY_ && opts.FilterSubject != fwcs {\n\t\t\tif acc == _EMPTY_ {\n\t\t\t\treturn nil, fmt.Errorf(\"filter by subject only valid with account filtering\")\n\t\t\t}\n\t\t\tfilter = opts.FilterSubject\n\t\t}\n\t}\n\n\tc := &Connz{\n\t\tOffset: offset,\n\t\tLimit:  limit,\n\t\tNow:    time.Now().UTC(),\n\t}\n\n\t// Open clients\n\tvar openClients []*client\n\t// Hold for closed clients if requested.\n\tvar closedClients []*closedClient\n\n\tvar clist map[uint64]*client\n","sourceCodeStart":248,"sourceCodeEnd":284,"githubUrl":"https://github.com/nats-io/nats-server/blob/3a66a489d262bf89b71a71c955c94920394532f3/server/monitor.go#L248-L284","documentation":"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.","triggerScenarios":"Calling Connz with ConnzOptions.FilterSubject set while opts.Account (and the accounts list) is empty; requesting /connz?filter_subject=foo without an acc parameter.","commonSituations":"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.","solutions":["Add an account scope: Connz(&ConnzOptions{Accounts: []string{\"ACC\"}, FilterSubject: \"foo.bar\"})","Remove FilterSubject if you genuinely want all accounts","On the HTTP endpoint use /connz?acc=ACC&filter_subject=foo.bar"],"exampleFix":"// before\nconnz, err := s.Connz(&server.ConnzOptions{FilterSubject: \"foo.bar\"})\n// after\nconnz, err := s.Connz(&server.ConnzOptions{Accounts: []string{\"A\"}, FilterSubject: \"foo.bar\"})","handlingStrategy":"validation","validationCode":"func validConnzFilter(o *server.ConnzOptions) bool {\n\treturn o.FilterSubject == \"\" || len(o.Accounts) == 1 || o.Account != \"\"\n}","typeGuard":null,"tryCatchPattern":"cz, err := srv.Connz(opts)\nif err != nil && strings.Contains(err.Error(), \"filter by subject only valid\") {\n\treturn nil, fmt.Errorf(\"FilterSubject requires an account filter: %w\", err)\n}","preventionTips":["Whenever you set FilterSubject, set Accounts (single account) in the same options struct","In UIs, disable the subject filter input until an account is selected","Remember Subsz has different filtering rules; don't copy options between endpoints"],"tags":["monitoring","connz","invalid-options"],"backgroundTag":"invalid-monitoring-query-options","analyzedSha":"3a66a489d262bf89b71a71c955c94920394532f3","analyzedAt":"2026-09-02T04:41:54.247Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T15:18:49.778Z"}