nats-io/nats-server · error

sequence numbers for cache load did not match, %d vs %d

Error message

sequence numbers for cache load did not match, %d vs %d

What it means

Returned when loading a message from a file-store block's cache: the sequence number derived from the index does not match the sequence stored in the cached block structure (fsm.seq). The store clears the cache/offset and returns this error so the caller knows the cache state was invalid (e.g. indexes were stale and have been rebuilt).

Source

Thrown at server/filestore.go:9168

	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 {
		return nil, errDeletedMsg
	}

	if seq != fsm.seq { // See TestFileStoreInvalidIndexesRebuilt.
		mb.clearCacheAndOffset()
		return nil, fmt.Errorf("sequence numbers for cache load did not match, %d vs %d", seq, fsm.seq)
	}

	// Clear the check bit here after we know all is good.
	if !hashChecked {
		mb.cache.idx[seq-mb.cache.fseq] = (bi | cbit)
	}

	return fsm, nil
}

// Used when we are checking if discarding a message due to max msgs per subject will give us
// enough room for a max bytes condition.
// Lock should be already held.
func (fs *fileStore) sizeForSeq(seq uint64) int {
	if seq == 0 {
		return 0
	}
	var smv StoreMsg

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Retry the read — the store already cleared the cache and will rebuild indexes.
2. If it persists, stop the server and remove the stream's .idx/index files to force a rebuild.
3. Check for external modification of the data directory (backups restored partially).
4. Upgrade NATS Server if hitting a known index-rebuild bug on your version.

Example fix

// recovery: force index rebuild
// 1. stop nats-server
// 2. rm /path/jetstream/$ST/streams/<stream>/msg/blk/*.idx
// 3. restart nats-server

msg, err := stream.GetMsg(seq)
if err != nil && strings.Contains(err.Error(), "sequence numbers for cache load did not match") {
    // cache was invalidated; one retry should succeed after rebuild
    time.Sleep(50 * time.Millisecond)
    msg, err = stream.GetMsg(seq)
}

When it happens

Trigger: Reading a message by sequence when the block's cached first-sequence offset disagrees with the looked-up sequence — typically after an unclean shutdown or truncated/corrupted index where TestFileStoreInvalidIndexesRebuilt scenarios apply.

Common situations: Server killed without clean shutdown (kill -9, power loss), leftover stale index files being repaired, or copying/mixing stream data directories between servers.

Related errors

• fileStore requires file storage type in config
• filestore max block size is %s
• could not create hash: %v
• failed to compress block: %w
• failed to write to temporary file: %w

AI-assisted analysis of nats-io/nats-server@3a66a489d2 (2026-09-02). Data as JSON: /api/errors/684b15c35b16b677. Report an issue: GitHub.