nats-io/nats-server · error

sublist: invalid subject

Error message

sublist: invalid subject

What it means

Generic sublist guard: the subject passed to Insert/Match — e.g. an account import or mapping transformation, or a route advertisement — failed validity checks such as invalid wildcards, empty tokens, or a missing '*' at the required account token position. The offending subject string is the input at fault.

Source

Thrown at server/sublist.go:43

// 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. Fix wildcard placement and remove empty tokens in the subject
2. Validate subjects with IsValidSubject before mapping or registration
3. Check account import/mapping subject templates for typos

When it happens

Trigger: Thrown at server/sublist.go:43 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/e3705eb9f045603e. Report an issue: GitHub.