nats-io/nats-server · error

message sequence %d exceeds maximum message size

Error message

message sequence %d exceeds maximum message size

What it means

Validation guard during restore: the message's declared header+payload size exceeds the target stream's MaxMsgSize limit (when configured). The archive contains a message larger than the stream policy allows, so the restore is rejected rather than silently violating the stream's per-message size cap.

Source

Thrown at server/stream_backup.go:482

		}
		seq := hdr.Sequence
		if seq == 0 {
			// Sentinel "end of backup" if all fields are zero.
			if hdr.Timestamp == 0 && hdr.HeaderSize == 0 && hdr.PayloadSize == 0 {
				eob = true
				break
			}
			return nil, fmt.Errorf("expected message sequence")
		}
		if hdr.HeaderSize < 0 || hdr.PayloadSize < 0 || hdr.PayloadSize > math.MaxInt64-hdr.HeaderSize {
			return nil, fmt.Errorf("invalid message lengths for sequence %d", seq)
		}
		declaredSize := hdr.HeaderSize + hdr.PayloadSize
		if hdr.HeaderSize > mp || hdr.PayloadSize > mp-hdr.HeaderSize {
			return nil, fmt.Errorf("message sequence %d exceeds maximum payload size", seq)
		}
		if mms := int64(cfg.MaxMsgSize); mms >= 0 && (hdr.HeaderSize > mms || hdr.PayloadSize > mms-hdr.HeaderSize) {
			return nil, fmt.Errorf("message sequence %d exceeds maximum message size", seq)
		}
		var storedSizeRaw uint64
		switch cfg.Storage {
		case MemoryStorage:
			storedSizeRaw = memStoreMsgSizeRaw(len(hdr.Name), int(hdr.HeaderSize), int(hdr.PayloadSize))
		default:
			storedSizeRaw = fileStoreMsgSizeRaw(len(hdr.Name), int(hdr.HeaderSize), int(hdr.PayloadSize))
		}
		if storedSizeRaw > math.MaxInt64 {
			return nil, fmt.Errorf("snapshot message bytes exceed reserved restore size")
		}
		storedSize := int64(storedSizeRaw)
		if additional := storedSize - restoreRemaining; additional > 0 {
			jsa.updateUsage(tier, cfg.Storage, additional)
			restoreRemaining += additional
			if err := checkUsageLimits(); err != nil {
				return nil, err
			}

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Increase the stream's max_msg_size (and the server's max_payload) to accommodate the archived messages before restoring
2. Restore into a stream whose limits match or exceed those of the source stream
3. Confirm the archived header sizes are accurate and not corrupted

When it happens

Trigger: Thrown at server/stream_backup.go:482 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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