{"record":{"id":"289180f8fab5a954","repo":"nats-io/nats-server","slug":"misaligned-wal-will-truncate","errorCode":null,"errorMessage":"Misaligned WAL, will truncate","messagePattern":"Misaligned WAL, will truncate","errorType":"console","errorClass":null,"httpStatus":null,"severity":"error","filePath":"server/raft.go","lineNumber":594,"sourceCode":"\n\t\t// This process will queue up entries on our applied queue but prior to the upper\n\t\t// state machine running. So we will monitor how much we have queued and if we\n\t\t// reach a limit will pause the apply queue and resume inside of run() go routine.\n\t\tconst maxQsz = 32 * 1024 * 1024 // 32MB max\n\n\t\t// It looks like there are entries we have committed but not applied\n\t\t// yet. Replay them.\n\t\tfor index, qsz := state.FirstSeq, 0; index <= state.LastSeq; index++ {\n\t\t\tae, err := n.loadEntry(index)\n\t\t\t// The first entry in our WAL initializes state but must align with our snapshot if we had one.\n\t\t\t// Importantly, check this first, as we might need to truncate the WAL further than the index.\n\t\t\tif index == state.FirstSeq {\n\t\t\t\t// If the entry is missing, corrupt, or doesn't align with the snapshot, truncate the WAL.\n\t\t\t\tif err != nil || ae == nil || ae.pindex != index-1 || n.pindex != ae.pindex {\n\t\t\t\t\tif err != nil {\n\t\t\t\t\t\tn.warn(\"Could not load %d from WAL [%+v]: %v\", index, state, err)\n\t\t\t\t\t} else {\n\t\t\t\t\t\tn.warn(\"Misaligned WAL, will truncate\")\n\t\t\t\t\t}\n\t\t\t\t\t// Truncate to the snapshot or beginning if there is none.\n\t\t\t\t\ttruncateAndErr(n.pindex)\n\t\t\t\t\tbreak\n\t\t\t\t}\n\t\t\t\tn.pterm, n.pindex = ae.pterm, ae.pindex\n\t\t\t\tif ae.commit > 0 && ae.commit > n.commit {\n\t\t\t\t\tn.commit = ae.commit\n\t\t\t\t}\n\t\t\t}\n\t\t\tif err != nil {\n\t\t\t\tn.warn(\"Could not load %d from WAL [%+v]: %v\", index, state, err)\n\t\t\t\t// Truncate to the previous correct entry.\n\t\t\t\ttruncateAndErr(index - 1)\n\t\t\t\tbreak\n\t\t\t}\n\t\t\tif ae.pindex != index-1 {\n\t\t\t\tn.warn(\"Corrupt WAL, will truncate\")","sourceCodeStart":576,"sourceCodeEnd":612,"githubUrl":"https://github.com/nats-io/nats-server/blob/3a66a489d262bf89b71a71c955c94920394532f3/server/raft.go#L576-L612","documentation":"During WAL replay after restart, the first entry's index did not line up with the position expected given the recovered snapshot (the WAL contains entries that do not follow the snapshot boundary). The WAL is truncated back to the snapshot (or the beginning if none) and replay restarts from a consistent point.","triggerScenarios":"Thrown at server/raft.go:594 when the library encounters an invalid state.","commonSituations":"See trigger scenarios.","solutions":["No action needed; truncation self-heals the log to the snapshot boundary","Data after the truncation point is re-replicated from the leader","Frequent occurrences suggest unclean shutdowns or disk write issues"],"exampleFix":null,"handlingStrategy":"fallback","validationCode":null,"typeGuard":null,"tryCatchPattern":null,"preventionTips":[],"tags":[],"backgroundTag":null,"analyzedSha":"3a66a489d262bf89b71a71c955c94920394532f3","analyzedAt":"2026-09-02T04:41:54.247Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}