nats-io/nats-server · error

Corrupt WAL, will truncate

Error message

Corrupt WAL, will truncate

What it means

During WAL replay, a successfully loaded entry's pindex did not equal index-1, i.e. the log chain has a gap or out-of-order entry (torn write mid-record can leave a load error instead; this is the variant where records decode but do not chain). The WAL is truncated to the previous correct entry.

Source

Thrown at server/raft.go:612

						n.warn("Misaligned WAL, will truncate")
					}
					// Truncate to the snapshot or beginning if there is none.
					truncateAndErr(n.pindex)
					break
				}
				n.pterm, n.pindex = ae.pterm, ae.pindex
				if ae.commit > 0 && ae.commit > n.commit {
					n.commit = ae.commit
				}
			}
			if err != nil {
				n.warn("Could not load %d from WAL [%+v]: %v", index, state, err)
				// Truncate to the previous correct entry.
				truncateAndErr(index - 1)
				break
			}
			if ae.pindex != index-1 {
				n.warn("Corrupt WAL, will truncate")
				// Truncate to the previous correct entry.
				truncateAndErr(index - 1)
				break
			}
			n.processAppendEntry(ae, nil)
			// Check how much we have queued up so far to determine if we should pause.
			for _, e := range ae.entries {
				qsz += len(e.Data)
				if qsz > maxQsz && !n.paused {
					n.PauseApply()
				}
			}
		}
	}

	n.debug("Started (cluster size %d, quorum %d)", n.csz, n.qn)

	// Check if we need to start in observer mode due to lame duck status.

View on GitHub (pinned to 3a66a489d2)

Solutions

1. No action needed; the WAL is self-truncated to the last chained entry
2. Entries after the break are re-replicated from the leader
3. Investigate storage durability if misalignment recurs

When it happens

Trigger: Thrown at server/raft.go:612 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/5f541722d654dae6. Report an issue: GitHub.