nats-io/nats-server · error

processGatewaySubjectSub Parse Error: '%s'

Error message

processGatewaySubjectSub Parse Error: '%s'

What it means

Raised inside processGatewaySubjectSub when the raw gateway SUB arguments do not have exactly 2 fields (account, subject) or 4 fields (account, subject, queue, weight). It indicates a malformed gateway subscription message arriving from a remote gateway.

Source

Thrown at server/gateway.go:2044

// from remote gateway.
// <Invoked from outbound connection's readLoop>
func (c *client) processGatewayRSub(arg []byte) error {
	// Indicate activity.
	c.in.subs++

	var (
		queue []byte
		qw    int32
	)

	args := splitArg(arg)
	switch len(args) {
	case 2:
	case 4:
		queue = args[2]
		qw = int32(parseSize(args[3]))
	default:
		return fmt.Errorf("processGatewaySubjectSub Parse Error: '%s'", arg)
	}
	accName := args[0]
	subject := args[1]

	var (
		e          *outsie
		useSl      bool
		newe       bool
		callUpdate bool
		srv        *Server
		sub        *subscription
	)

	// Possibly execute this on exit after all locks have been released.
	// If callUpdate is true, srv and sub will be not nil.
	defer func() {
		if callUpdate {
			srv.updateInterestForAccountOnGateway(string(accName), sub, 1)

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Align NATS server versions across all gateway-connected clusters
2. Enable gateway trace logging (debug/trace flags) to inspect the malformed frame and its origin
3. Inspect network path (load balancers, proxies) for frame corruption or truncation
4. Restart the offending gateway connection after fixing the peer

// Same family as 490: validate inter-server compatibility before forming gateway connections
// and run with gateway tracing in staging to detect malformed SUB frames.
// nats-server flag example: --cluster ... --gateway ... --trace_verbose (staging only)

When it happens

Trigger: Remote gateway sends 'LS+/RS+' subscription protocol with wrong field count: missing account or subject, or a queue+weight pair where only one is present; parseSize on args[3] may also fail on non-numeric queue weight.

Common situations: Version skew between clustered NATS servers changing the gateway SUB format; broken middleware/proxy truncating frames; a rogue process speaking garbage on the gateway port.

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

• processGatewaySubjectUnsub %s
• remote leafnode has same cluster name
• attempted to connect to gateway port
• wrong gateway
• gateway name cannot contain spaces

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