nats-io/nats-server · error

Partial cache: slot index %d is less than cache buffer len %

Error message

Partial cache: slot index %d is less than cache buffer len %d

What it means

A warning logged when the block-offset byte index derived from a sequence (seq - cache.fseq) points past the end of the partial cache buffer. This is an internal consistency guard: the lookup cannot be resolved from the partial cache, errPartialCache is returned, and the caller falls back to reading the block from disk.

Source

Thrown at server/filestore.go:9144

		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:]

	// We use the high bit to denote we have already checked the checksum.
	var hh *highwayhash.Digest64
	if !hashChecked {
		hh = mb.hh // This will force the hash check in msgFromBuf.
	}

	// Parse from the raw buffer.
	fsm, err := mb.msgFromBufEx(buf, sm, hh, doCopy)
	if err != nil || fsm == nil {
		return nil, err
	}

	// Deleted messages that are decoded return a 0 for sequence.
	if fsm.seq == 0 {

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Usually harmless: caller loads the block from disk as fallback
2. If persistent, check for cache corruption; restart the server to rebuild caches
3. Report to maintainers if reproducible, as it may indicate index/buffer drift

When it happens

Trigger: Thrown at server/filestore.go:9144 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/5fdc712e57724da4. Report an issue: GitHub.