nats-io/nats-server · error

Partial cache: seq %d is less than cache fseq %d

Error message

Partial cache: seq %d is less than cache fseq %d

What it means

A warning logged when a cache lookup requests a sequence below the partial cache's first sequence (cache.fseq). The partial cache only covers sequences from fseq onward, so the request cannot be served from it and errPartialCache is returned; the caller then loads from disk.

Source

Thrown at server/filestore.go:9130

		var reason string
		if mb.cache == nil {
			reason = "no cache"
		} else if mb.cache.fseq == 0 {
			reason = "fseq is 0"
		} else if len(mb.cache.idx) == 0 {
			reason = "no idx present"
		} else {
			reason = "cache buf empty"
		}
		mb.fs.warn("Cache lookup for sequence %d in block %d detected no cache: %s", seq, mb.index, reason)
		if mb.cache != nil {
			mb.tryForceExpireCacheLocked()
		}
		return nil, errNoCache
	}
	// Check partial cache status.
	if seq < mb.cache.fseq {
		mb.fs.warn("Partial cache: seq %d is less than cache fseq %d", seq, mb.cache.fseq)
		return nil, errPartialCache
	}

	bi, _, hashChecked, err := mb.slotInfo(int(seq - mb.cache.fseq))
	if err != nil {
		return nil, err
	}

	// Update cache activity.
	mb.llts = ats.AccessTime()

	li := int(bi)
	if li >= len(mb.cache.buf) {
		mb.fs.warn("Partial cache: slot index %d is less than cache buffer len %d", li, len(mb.cache.buf))
		return nil, errPartialCache
	}
	buf := mb.cache.buf[li:]

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Typically benign — caller falls back to disk reads for older sequences
2. If frequent, adjust cache start/expiry policy so needed sequences remain cached
3. Verify consumers are not repeatedly reading far older sequences (retention policy)

When it happens

Trigger: Thrown at server/filestore.go:9130 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/470a0032e75bfd75. Report an issue: GitHub.