processRoutedHeaderMsgArgs Header Size larger then TotalSize

Error message

processRoutedHeaderMsgArgs Header Size larger then TotalSize: '%s'

What it means

When a route (or leaf/gateway forwarded) HPUB message is parsed, the protocol args carry a header size and a total payload size. If the declared header byte count (c.pa.hdr) exceeds the declared total size (c.pa.size), the protocol line is internally inconsistent, so processRoutedHeaderMsgArgs rejects it. This guards against corrupt or malicious inter-server traffic.

Source

Thrown at server/route.go:365

		// Grab size.
		c.pa.szb = args[len(args)-1]
		c.pa.size = parseSize(c.pa.szb)

		// Grab queue names.
		if c.pa.reply != nil {
			c.pa.queues = args[4 : len(args)-2]
		} else {
			c.pa.queues = args[3 : len(args)-2]
		}
	}
	if c.pa.hdr < 0 {
		return fmt.Errorf("processRoutedHeaderMsgArgs Bad or Missing Header Size: '%s'", arg)
	}
	if c.pa.size < 0 {
		return fmt.Errorf("processRoutedHeaderMsgArgs Bad or Missing Size: '%s'", args)
	}
	if c.pa.hdr > c.pa.size {
		return fmt.Errorf("processRoutedHeaderMsgArgs Header Size larger then TotalSize: '%s'", arg)
	}

	// Common ones processed after check for arg length
	c.pa.account = args[0]
	c.pa.subject = args[1]
	if len(an) > 0 {
		c.pa.pacache = c.pa.subject
	} else {
		c.pa.pacache = arg[:len(args[0])+len(args[1])+1]
	}
	return nil
}

// Process an inbound RMSG or LMSG specification from the remote route.
func (c *client) processRoutedMsgArgs(arg []byte) error {
	// Unroll splitArgs to avoid runtime/heap issues
	args := c.argsa[:0]
	var an []byte

View on GitHub (pinned to 3a66a489d2)

Solutions

Inspect the client or intermediary that produced the message and fix the size fields so headers <= total size
Verify the route connection is not passing through a corrupting proxy or buggy middleware
Ensure all servers in the cluster run a compatible, recent NATS Server version
Check sender code that serializes HPUB: header byte length must be added to, not replace, the total size

Example fix

// before (sender)
fmt.Printf("HMSG %s %s %d %d\r\n", subj, reply, hdrLen, hdrLen)
// after
fmt.Printf("HMSG %s %s %d %d\r\n", subj, reply, hdrLen, hdrLen+payloadLen)

Defensive patterns

Strategy: validation

Validate before calling

// Go client/server operator: validate HPUB sizes before publishing
if hdrLen > totalSize {
    return fmt.Errorf("header size %d exceeds total size %d", hdrLen, totalSize)
}

Prevention

Always compute totalSize as headerLen + payloadLen when emitting HPUB
Keep cluster links free of rewriting proxies
Run identical NATS Server versions across the cluster

When it happens

Trigger: A routed HMSG/HPUB whose args encode a header length greater than the total message size, e.g. 'HMSG <subject> <reply> <hdrSize> <totalSize>' where hdrSize > totalSize; produced by a corrupt, buggy, or hostile upstream server/route connection.

Common situations: NATS cluster peering with a server that mangles protocol lines (proxy rewriting, TCP corruption), custom client or bridge sending hand-crafted HPUB with swapped header/total size fields, or fuzzing/attack traffic on the route port.

Related errors

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