nats-io/nats-server · error

expected message sequence

Error message

expected message sequence

What it means

Validation guard in the restore message loop: a message header arrived with Sequence == 0, but it was not the all-zero end-of-backup sentinel (Timestamp, HeaderSize, PayloadSize all zero). Sequence zero is reserved for the sentinel, so any other zero-sequence header indicates a corrupted, truncated, or incompatible backup archive.

Source

Thrown at server/stream_backup.go:472

	}

	store := mset.store
	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))
		}

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Regenerate the backup archive and verify its transfer integrity (checksums)
2. Restore with the same server version that created the archive
3. Inspect the tar stream around the failing entry to confirm the header encoding is intact

When it happens

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