nats-io/nats-server · error

processLeafSub Parse Error: '%s'

Error message

processLeafSub Parse Error: '%s'

What it means

Leaf-node protocol parse guard: an incoming subscription line from the hub had an argument count other than 1 (plain sub) or 3 (queue sub with weight), so the arguments cannot be interpreted as a subscription.

Source

Thrown at server/leafnode.go:2961

	sub := &subscription{client: c, leaf: true}

	delta := int32(1)
	switch len(args) {
	case 1:
		sub.queue = nil
	case 3:
		sub.queue = args[1]
		sub.qw = int32(parseSize(args[2]))
		// TODO: (ik) We should have a non empty queue name and a queue
		// weight >= 1. For 2.11, we may want to return an error if that
		// is not the case, but for now just overwrite `delta` if queue
		// weight is greater than 1 (it is possible after a reconnect/
		// server restart to receive a queue weight > 1 for a new sub).
		if sub.qw > 1 {
			delta = sub.qw
		}
	default:
		return fmt.Errorf("processLeafSub Parse Error: '%s'", arg)
	}
	sub.subject = args[0]

	c.mu.Lock()
	if c.isClosed() {
		c.mu.Unlock()
		return nil
	}

	acc := c.acc
	// Guard against LS+ arriving before CONNECT has been processed, which
	// can happen when compression is enabled.
	if acc == nil {
		c.mu.Unlock()
		c.sendErr("Authorization Violation")
		c.closeConnection(ProtocolViolation)
		return nil
	}

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Check for version mismatch between leaf nodes
2. Inspect the raw protocol traffic for corruption or non-NATS intermediaries
3. Reproduce with debug logging to capture the malformed line

When it happens

Trigger: Thrown at server/leafnode.go:2961 when the library encounters an invalid state.

Common situations: See trigger scenarios.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

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