nats-io/nats-server · error

gsl: invalid subject

Error message

gsl: invalid subject

What it means

ErrInvalidSubject ('gsl: invalid subject') is the generic sublist error returned when a subject string is not a valid NATS subject. In server/accounts.go it is returned when validating account-scoped subjects (token position checks) and when validating subject-mapping from/to subjects with IsValidSubject. It is the shared sentinel for all 'this subject string is malformed' cases in the sublist packages.

Source

Thrown at server/gsl/gsl.go:40

// 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   = '.'
	_EMPTY_ = ""
)

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

// SimpleSublist is an alias type for GenericSublist that takes
// empty values, useful for tracking interest only without any
// unnecessary allocations.
type SimpleSublist = GenericSublist[struct{}]

// NewSimpleSublist will create a simple sublist.
func NewSimpleSublist() *SimpleSublist {
	return &GenericSublist[struct{}]{root: newLevel[struct{}]()}
}

// A GenericSublist stores and efficiently retrieves subscriptions.
type GenericSublist[T comparable] struct {
	sync.RWMutex

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Print/inspect the offending subject and fix its syntax: no empty tokens, valid characters, wildcards (*) only as full tokens.
2. For account-position validation, ensure the token at the expected account position is exactly "*" or supply enough tokens (len(token) >= accountPos).
3. Validate subjects programmatically with server.IsValidSubject before inserting/registration.

Example fix

// before
sub, _ := subject  // e.g. "foo..bar" from joining
sub := strings.Join(parts, ".")
// after
if !IsValidSubject(sub) {
    return fmt.Errorf("bad subject %q", sub)
}

if !gsl.IsValidSubject(subject) {
    return fmt.Errorf("invalid subject %q", subject)
}

if errors.Is(err, gsl.ErrInvalidSubject) {
    return fmt.Errorf("bad subject syntax: %w", err)
}

When it happens

Trigger: Inserting/subscribing with a subject containing empty tokens ('foo..bar'), illegal characters, a leading/trailing dot, or failing account-position wildcard checks (token[accountPos-1] != "*"); mapping validation where !IsValidSubject(from) || !IsValidSubject(to) (server/accounts.go:1676).

Common situations: Config files with malformed subjects (double dots, spaces, wrong wildcard placement), code building subjects with string concatenation producing empty tokens, account bindings where the wildcard is not at the required token position.

Related errors

• invalid subject-queue %q
• max_ack_pending must be set to -1
• subject has exceeded number of tokens limit
• bad sampling percentage, should be 1-100
• stream import prefix can not contain wildcard tokens

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