nats-io/nats-server · error

Detected skew in subject-based total (%d) vs raw total (%d),

Error message

Detected skew in subject-based total (%d) vs raw total (%d), rebuilding

What it means

A consistency check found the sum of per-subject message totals (psim) differs from the stream's raw message count — index/subject bookkeeping has diverged (a known past bug class). The store rebuilds its state from the message blocks to re-sync the counters.

Source

Thrown at server/filestore.go:5961

	fblk, lblk := uint32(math.MaxUint32), uint32(0)
	fs.psim.IterFast(func(subj []byte, psi *psi) bool {
		numMsgs += psi.total
		if psi.total > maxMsgsPer {
			needAttention.Insert(subj, psi.total)
			if psi.fblk < fblk {
				fblk = psi.fblk
			}
			if psi.lblk > lblk {
				lblk = psi.lblk
			}
		}
		return true
	})

	// We had an issue with a use case where psim (and hence fss) were correct but idx was not and was not properly being caught.
	// So do a quick sanity check here. If we detect a skew do a rebuild then re-check.
	if numMsgs != fs.state.Msgs {
		fs.warn("Detected skew in subject-based total (%d) vs raw total (%d), rebuilding", numMsgs, fs.state.Msgs)
		// Clear any global subject state.
		fs.psim, fs.tsl = fs.psim.Empty(), 0
		for _, mb := range fs.blks {
			ld, _, err := mb.rebuildState()
			if err != nil {
				return err
			} else if ld != nil {
				fs.addLostData(ld)
			}
			if err = fs.populateGlobalPerSubjectInfo(mb); err != nil {
				return err
			}
		}
		// Rebuild fs state too.
		fs.rebuildStateLocked(nil)
		// Need to redo blocks that need attention.
		needAttention.Empty()
		fblk, lblk = uint32(math.MaxUint32), uint32(0)

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Let the automatic rebuildState repair the skew
2. Run stream and message integrity checks (JS API) after recovery
3. Report recurring skew as a bug with stream details

When it happens

Trigger: Thrown at server/filestore.go:5961 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/0a8d4e56982e6002. Report an issue: GitHub.