nats-io/nats-server · error

processSub Parse Error: %q

Error message

processSub Parse Error: %q

What it means

The SUB protocol operation had an invalid argument count. processSub accepts 2 args (subject, sid) or 3 args (subject, queue, sid); anything else returns this parse error. Note the comment in the source: the parse error is returned but for actual subscription errors the connection is not closed; a parse error here does terminate the client connection.

Source

Thrown at server/client.go:3049

	arg := make([]byte, len(argo))
	copy(arg, argo)
	args := splitArg(arg)
	var (
		subject []byte
		queue   []byte
		sid     []byte
	)
	switch len(args) {
	case 2:
		subject = args[0]
		queue = nil
		sid = args[1]
	case 3:
		subject = args[0]
		queue = args[1]
		sid = args[2]
	default:
		return fmt.Errorf("processSub Parse Error: %q", arg)
	}
	// If there was an error, it has been sent to the client. We don't return an
	// error here to not close the connection as a parsing error.
	c.processSub(subject, queue, sid, nil, noForward)
	return nil
}

func (c *client) processSub(subject, queue, bsid []byte, cb msgHandler, noForward bool) (*subscription, error) {
	return c.processSubEx(subject, queue, bsid, cb, noForward, false, false)
}

func (c *client) processSubEx(subject, queue, bsid []byte, cb msgHandler, noForward, si, rsi bool) (*subscription, error) {
	// Create the subscription
	sub := &subscription{client: c, subject: subject, queue: queue, sid: bsid, icb: cb, si: si, rsi: rsi}

	c.mu.Lock()

	// Indicate activity.

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Send SUB with exactly `SUB <subject> <sid>` or `SUB <subject> <queue> <sid>` followed by CRLF
2. Fix or upgrade the client library building SUB frames
3. Check logs/traffic capture for the exact malformed SUB line

Example fix

// before
SUB subject
// after
SUB subject 1

if queue == "" {
    frame = fmt.Sprintf("SUB %s %s\r\n", subject, sid)
} else {
    frame = fmt.Sprintf("SUB %s %s %s\r\n", subject, queue, sid)
}

When it happens

Trigger: Client sends `SUB` with 0, 1, or more than 3 tokens, e.g. `SUB subject` (missing sid) or `SUB a b c d`, so the switch falls to default.

Common situations: Hand-written SUB frames in scripts or tests, queue-group clients emitting an extra token, proxy mangling whitespace, buggy custom client.

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

• processUnsub 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/7bfa106b58fbdeef. Report an issue: GitHub.