nats-io/nats-server · error

processUnsub Parse Error: %q

Error message

processUnsub Parse Error: %q

What it means

The UNSUB protocol operation had an invalid argument count. processUnsub expects 1 arg (sid) or 2 args (sid, max-messages); any other count returns this parse error and the connection is treated as a protocol violator.

Source

Thrown at server/client.go:3527

	// We can skip subscriptions on reserved replies.
	if acc != nil && !isReservedReply(sub.subject) {
		acc.checkForReverseEntry(string(sub.subject), nil, true)
	}
}

func (c *client) processUnsub(arg []byte) error {
	args := splitArg(arg)
	var sid []byte
	max := int64(-1)

	switch len(args) {
	case 1:
		sid = args[0]
	case 2:
		sid = args[0]
		max = int64(parseSize(args[1]))
	default:
		return fmt.Errorf("processUnsub Parse Error: %q", arg)
	}

	var sub *subscription
	var ok, unsub bool

	c.mu.Lock()

	// Indicate activity.
	c.in.subs++

	// Grab connection type.
	kind := c.kind
	srv := c.srv
	var acc *Account

	updateGWs := false
	if sub, ok = c.subs[string(sid)]; ok {
		acc = c.acc

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Send `UNSUB <sid>` or `UNSUB <sid> <maxMsgs>` followed by CRLF, exactly 1 or 2 args
2. Fix the client code that formats the UNSUB frame, ensuring the optional max is a valid integer token
3. Use server debug logs to see the offending line

Example fix

// before
UNSUB 1 10 extra
// after
UNSUB 1 10

if maxMsgs > 0 {
    frame = fmt.Sprintf("UNSUB %s %d\r\n", sid, maxMsgs)
} else {
    frame = fmt.Sprintf("UNSUB %s\r\n", sid)
}

When it happens

Trigger: Client sends `UNSUB` with 0 or 3+ tokens, e.g. bare `UNSUB`, or `UNSUB sid max extra`, so the switch on len(args) falls to default.

Common situations: Custom or scripted clients appending extra tokens, max-message limit logic emitting a malformed second arg, proxy interference with line framing.

Understand the failure class

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

Related errors

• processSub Parse Error: %q
• processHeaderPub Bad or Missing Header Size: %q
• processHeaderPub Bad or Missing Total Size: %q
• processHeaderPub Header Size larger then TotalSize: %q
• processPub Parse Error: %q

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