What causes "invalid subject-queue %q" in nats-io/nats-server?

Supply a non-empty, valid NATS subject as the first token of the string.

invalid subject-queue %q

Error message

invalid subject-queue %q

What it means

splitSubjectQueue was given an empty or whitespace-only string for the subject-queue parameter (used when a client sends a deliver-subject/queue style subscription spec, e.g. as part of queue subscription permissions or $JS API consumption of '<subject> <queue>'). After splitting on whitespace there are zero tokens, so the function cannot produce a subject and returns this error.

Source

Thrown at server/client.go:1084

	if c.user == nil || !c.user.defaultPerms {
		return false
	}
	if perms == nil {
		c.user.Permissions = nil
		c.perms = nil
		c.mperms = nil
		c.darray = nil
		return true
	}
	c.user.Permissions = perms.clone()
	c.setPermissions(c.user.Permissions)
	return true
}

func splitSubjectQueue(sq string) ([]byte, []byte, error) {
	vals := strings.Fields(strings.TrimSpace(sq))
	if len(vals) == 0 {
		return nil, nil, fmt.Errorf("invalid subject-queue %q", sq)
	}
	s := []byte(vals[0])
	var q []byte
	if len(vals) == 2 {
		q = []byte(vals[1])
	} else if len(vals) > 2 {
		return nil, nil, fmt.Errorf("invalid subject-queue %q", sq)
	}
	if !IsValidSubject(vals[0]) || (len(q) > 0 && !IsValidSubject(vals[1])) {
		return nil, nil, fmt.Errorf("invalid subject-queue %q", sq)
	}
	return s, q, nil
}

// Initializes client.perms structure.
// Lock is held on entry.
func (c *client) setPermissions(perms *Permissions) {
	if perms == nil {

View on GitHub (pinned to 3a66a489d2)

Solutions

Supply a non-empty, valid NATS subject as the first token of the string.
Check the client/request producing the empty value (config field, variable interpolation) and default or reject it before sending.
If queue subscription is intended, format as '<subject> <queue>' with exactly two whitespace-separated tokens.

Example fix

// before
cfg.Subject = ""
// after
cfg.Subject = "orders.>" // must be a non-empty valid subject

Defensive patterns

Strategy: validation

Validate before calling

func validSubjectQueue(sq string) bool {
    f := strings.Fields(strings.TrimSpace(sq))
    return len(f) >= 1 && len(f) <= 2
}

Prevention

Never interpolate possibly-empty variables into subject strings.
Trim and validate input before sending subscription requests.
Prefer official NATS client APIs over manual protocol strings.

When it happens

Trigger: Calling splitSubjectQueue (from subject/queue parsing in client.go) with sq == "" or a string containing only spaces/tabs, e.g. an empty token supplied where '<subject> [<queue>]' is expected.

Common situations: A client library or operator config sends an empty subject field; a subscription request with an all-whitespace subject; automation tooling that interpolates an unset variable into the subject position.

Related errors

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