nats-io/nats-server · error

sublist: notification already registered

Error message

sublist: notification already registered

What it means

RegisterNotification: the exact channel being registered is already present in that subject's notification list, so the duplicate registration is rejected instead of double-notifying on changes.

Source

Thrown at server/sublist.go:46

// 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
}

// A Sublist stores and efficiently retrieves subscriptions.

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Reuse the existing registration instead of re-registering
2. Snapshot-and-clear or unregister before re-registering the same channel
3. Track registrations caller-side to avoid duplicates

When it happens

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