nats-io/nats-server · error

subject filter '%s' for the source: %w

Error message

subject filter '%s' for the source: %w

What it means

Stream-creation validation for Sources: a source's FilterSubject is set but IsValidSubject rejected it — invalid characters or malformed wildcard placement in the source's subject filter. The filter string is echoed and the error wraps ErrBadSubject.

Source

Thrown at server/stream.go:964

				}
				// check the transform, if any, is valid
				if st.Destination != _EMPTY_ {
					if _, err = NewSubjectTransform(st.Source, st.Destination); err != nil {
						jsa.mu.Unlock()
						return nil, fmt.Errorf("subject transform from '%s' to '%s' for the mirror: %w", st.Source, st.Destination, err)
					}
				}
			}
		}
	}

	// Setup our internal indexed names here for sources and check if the transforms (if any) are valid.
	for _, ssi := range cfg.Sources {
		if len(ssi.SubjectTransforms) == 0 {
			// check the filter, if any, is valid
			if ssi.FilterSubject != _EMPTY_ && !IsValidSubject(ssi.FilterSubject) {
				jsa.mu.Unlock()
				return nil, fmt.Errorf("subject filter '%s' for the source: %w", ssi.FilterSubject, ErrBadSubject)
			}
		} else {
			for _, st := range ssi.SubjectTransforms {
				if st.Source != _EMPTY_ && !IsValidSubject(st.Source) {
					jsa.mu.Unlock()
					return nil, fmt.Errorf("subject filter '%s' for the source: %w", st.Source, ErrBadSubject)
				}
				// check the transform, if any, is valid
				if st.Destination != _EMPTY_ {
					if _, err = NewSubjectTransform(st.Source, st.Destination); err != nil {
						jsa.mu.Unlock()
						return nil, fmt.Errorf("subject transform from '%s' to '%s' for the source: %w", st.Source, st.Destination, err)
					}
				}
			}
		}
	}

View on GitHub (pinned to 3a66a489d2)

Solutions

  1. Fix the source's FilterSubject to a valid subject string.
  2. Drop the filter to consume the whole upstream stream.
  3. Validate the filter with IsValidSubject before building the config.

Example fix

// before
Sources: []StreamSource{{Name: "A", FilterSubject: "x..y"}}
// after
Sources: []StreamSource{{Name: "A", FilterSubject: "x.y"}}
Defensive patterns

Strategy: validation

Validate before calling

for _, s := range cfg.Sources {
  if s.FilterSubject != "" && !nats.IsValidSubject(s.FilterSubject) { return fmt.Errorf("bad source filter %q", s.FilterSubject) }
}

Try / catch

_, err := js.AddStream(cfg)
var apiErr *nats.APIError
if err != nil && errors.As(err, &apiErr) && errors.Is(err, nats.ErrBadSubject) { /* fix FilterSubject of offending source */ }

Prevention

When it happens

Trigger: AddStream/UpdateStream with cfg.Sources[i].FilterSubject invalid (malformed wildcard, double dots, illegal characters).

Common situations: Multi-source streams filtering subsets of upstream streams with a hand-typed filter, often copied between sources or templated from user input.

Related errors

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