nats-io/nats-server · error

invalid message lengths for sequence %d

Error message

invalid message lengths for sequence %d

What it means

Validation guard on the restore message header: HeaderSize or PayloadSize is negative, or their sum overflows int64. Such lengths cannot occur in a well-formed archive and indicate header corruption or an archive produced/modified by incompatible tooling; the check runs before any allocation based on these sizes.

Source

Thrown at server/stream_backup.go:475

	lseq := nstate.FirstSeq - 1
	eob := false
	mp := int64(s.getOpts().MaxPayload)
	for {
		hdr, err := tr.Next()
		if err != nil {
			return nil, err
		}
		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")
		}

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Regenerate the backup and verify it was not modified or truncated in transit
2. Use matching server versions for backup and restore
3. If importing third-party archives, validate header fields before feeding the tar stream to restore

When it happens

Trigger: Thrown at server/stream_backup.go:475 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/39ec62d2a0f043f5. Report an issue: GitHub.