What causes "processHeaderPub Header Size larger then TotalSize: %q" in nats-io/nats-server?

Fix the client so total size is always >= header size (total = hdr + payload len)

processHeaderPub Header Size larger then TotalSize: %q

Error message

processHeaderPub Header Size larger then TotalSize: %q

What it means

Client protocol parse guard: in an HPUB protocol line the parsed header size (c.pa.hdr) exceeds the parsed total payload size (c.pa.size), which is impossible for a well-formed message and indicates a malformed or corrupted protocol line.

Source

Thrown at server/client.go:2929

	case 4:
		c.pa.subject = args[0]
		c.pa.reply = args[1]
		c.pa.hdr = parseSize(args[2])
		c.pa.size = parseSize(args[3])
		c.pa.hdb = args[2]
		c.pa.szb = args[3]
	default:
		return fmt.Errorf("processHeaderPub Parse Error: %q", arg)
	}
	if c.pa.hdr < 0 {
		return fmt.Errorf("processHeaderPub Bad or Missing Header Size: %q", arg)
	}
	// If number overruns an int64, parseSize() will have returned a negative value
	if c.pa.size < 0 {
		return fmt.Errorf("processHeaderPub Bad or Missing Total Size: %q", arg)
	}
	if c.pa.hdr > c.pa.size {
		return fmt.Errorf("processHeaderPub Header Size larger then TotalSize: %q", arg)
	}
	maxPayload := atomic.LoadInt32(&c.mpay)
	// Use int64() to avoid int32 overrun...
	if maxPayload != jwt.NoLimit && int64(c.pa.size) > int64(maxPayload) {
		// If we are given the remaining read buffer (since we do blind reads
		// we may have the beginning of the message header/payload), we will
		// look for the tracing header and if found, we will generate a
		// trace event with the max payload ingress error.
		// Do this only for CLIENT connections.
		if c.kind == CLIENT && c.pa.hdr > 0 && len(remaining) > 0 {
			hdr := remaining[:min(len(remaining), c.pa.hdr)]
			c.sendMsgTraceIngressErrEvent(hdr, ErrMaxPayload)
		}
		c.maxPayloadViolation(c.pa.size, maxPayload)
		return ErrMaxPayload
	}
	if c.opts.Pedantic && !IsValidLiteralSubject(bytesToString(c.pa.subject)) {
		c.sendErr("Invalid Publish Subject")

View on GitHub (pinned to 3a66a489d2)

Solutions

Fix the client so total size is always >= header size (total = hdr + payload len)
Check for swapped arguments in the client's HMSG formatting code
Enable NATS server debug logging to see the offending protocol line

Example fix

// before
HMSG subj reply 20 10
// after
HMSG subj reply 5 12

Defensive patterns

Strategy: validation

Validate before calling

if hdrSize > totalSize {
    return errors.New("header size cannot exceed total size")
}

Prevention

Assert hdr <= total in the client before writing the frame
Total = header length + payload length; derive one from the other
Add unit tests that frame HMSG messages with headers

When it happens

Trigger: Client sends `HMSG <subject> <reply> <hdr> <total>` with hdr > total, e.g. `HMSG s r 20 10`, so c.pa.hdr > c.pa.size.

Common situations: Client bug swapping or miscalculating the two size fields, header built larger than the buffer used to compute total size, hand-written protocol frames in tests/scripts.

Related errors

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