nats-io/nats-server · error

sublist: no matches found

Error message

sublist: no matches found

What it means

ErrNotFound from sublist Match: no subscription matches the subject being looked up. For most callers this is an expected negative result (nothing to deliver), not a fault — e.g. gsl.Remove returns it when the subject has no registrations to remove.

Source

Thrown at server/sublist.go:44

// Sublist is a routing mechanism to handle subject distribution and
// provides a facility to match subjects from published messages to
// interested subscribers. Subscribers can have wildcard subjects to
// match multiple published subjects.

// Common byte variables for wildcards and token separator.
const (
	pwc   = '*'
	pwcs  = "*"
	fwc   = '>'
	fwcs  = ">"
	tsep  = "."
	btsep = '.'
)

// Sublist related errors
var (
	ErrInvalidSubject    = errors.New("sublist: invalid subject")
	ErrNotFound          = errors.New("sublist: no matches found")
	ErrNilChan           = errors.New("sublist: nil channel")
	ErrAlreadyRegistered = errors.New("sublist: notification already registered")
)

const (
	// cacheMax is used to bound limit the frontend cache
	slCacheMax = 1024
	// If we run a sweeper we will drain to this count.
	slCacheSweep = 256
	// plistMin is our lower bounds to create a fast plist for Match.
	plistMin = 256
)

// SublistResult is a result structure better optimized for queue subs.
type SublistResult struct {
	psubs []*subscription
	qsubs [][]*subscription // don't make this a map, too expensive to iterate
}

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Treat as an empty result and skip delivery or removal
2. Register interest (subscribe) before matching if a match was expected
3. Verify subject spelling and normalization before matching

When it happens

Trigger: Thrown at server/sublist.go:44 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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