{"record":{"id":"684b15c35b16b677","repo":"nats-io/nats-server","slug":"sequence-numbers-for-cache-load-did-not-match-d","errorCode":null,"errorMessage":"sequence numbers for cache load did not match, %d vs %d","messagePattern":"sequence numbers for cache load did not match, (.+?) vs (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"server/filestore.go","lineNumber":9168,"sourceCode":"\tvar hh *highwayhash.Digest64\n\tif !hashChecked {\n\t\thh = mb.hh // This will force the hash check in msgFromBuf.\n\t}\n\n\t// Parse from the raw buffer.\n\tfsm, err := mb.msgFromBufEx(buf, sm, hh, doCopy)\n\tif err != nil || fsm == nil {\n\t\treturn nil, err\n\t}\n\n\t// Deleted messages that are decoded return a 0 for sequence.\n\tif fsm.seq == 0 {\n\t\treturn nil, errDeletedMsg\n\t}\n\n\tif seq != fsm.seq { // See TestFileStoreInvalidIndexesRebuilt.\n\t\tmb.clearCacheAndOffset()\n\t\treturn nil, fmt.Errorf(\"sequence numbers for cache load did not match, %d vs %d\", seq, fsm.seq)\n\t}\n\n\t// Clear the check bit here after we know all is good.\n\tif !hashChecked {\n\t\tmb.cache.idx[seq-mb.cache.fseq] = (bi | cbit)\n\t}\n\n\treturn fsm, nil\n}\n\n// Used when we are checking if discarding a message due to max msgs per subject will give us\n// enough room for a max bytes condition.\n// Lock should be already held.\nfunc (fs *fileStore) sizeForSeq(seq uint64) int {\n\tif seq == 0 {\n\t\treturn 0\n\t}\n\tvar smv StoreMsg","sourceCodeStart":9150,"sourceCodeEnd":9186,"githubUrl":"https://github.com/nats-io/nats-server/blob/3a66a489d262bf89b71a71c955c94920394532f3/server/filestore.go#L9150-L9186","documentation":"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).","triggerScenarios":"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.","commonSituations":"Server killed without clean shutdown (kill -9, power loss), leftover stale index files being repaired, or copying/mixing stream data directories between servers.","solutions":["Retry the read — the store already cleared the cache and will rebuild indexes.","If it persists, stop the server and remove the stream's .idx/index files to force a rebuild.","Check for external modification of the data directory (backups restored partially).","Upgrade NATS Server if hitting a known index-rebuild bug on your version."],"exampleFix":"// recovery: force index rebuild\n// 1. stop nats-server\n// 2. rm /path/jetstream/$ST/streams/<stream>/msg/blk/*.idx\n// 3. restart nats-server","handlingStrategy":"retry","validationCode":null,"typeGuard":null,"tryCatchPattern":"msg, err := stream.GetMsg(seq)\nif err != nil && strings.Contains(err.Error(), \"sequence numbers for cache load did not match\") {\n    // cache was invalidated; one retry should succeed after rebuild\n    time.Sleep(50 * time.Millisecond)\n    msg, err = stream.GetMsg(seq)\n}","preventionTips":["Always shut down nats-server cleanly (SIGTERM), never SIGKILL.","Avoid copying stream data directories between servers while running.","Monitor server logs for index rebuild events after unclean shutdowns.","Keep NATS Server current for index-rebuild fixes."],"tags":["filestore","cache","sequence","jetstream","go"],"backgroundTag":"sequence-mismatch","analyzedSha":"3a66a489d262bf89b71a71c955c94920394532f3","analyzedAt":"2026-09-02T04:41:54.247Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T15:18:49.778Z"}