nats-io/nats-server · error

Misaligned WAL, will truncate

Error message

Misaligned WAL, will truncate

What it means

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.

Source

Thrown at server/raft.go:594

		// This process will queue up entries on our applied queue but prior to the upper
		// state machine running. So we will monitor how much we have queued and if we
		// reach a limit will pause the apply queue and resume inside of run() go routine.
		const maxQsz = 32 * 1024 * 1024 // 32MB max

		// It looks like there are entries we have committed but not applied
		// yet. Replay them.
		for index, qsz := state.FirstSeq, 0; index <= state.LastSeq; index++ {
			ae, err := n.loadEntry(index)
			// The first entry in our WAL initializes state but must align with our snapshot if we had one.
			// Importantly, check this first, as we might need to truncate the WAL further than the index.
			if index == state.FirstSeq {
				// If the entry is missing, corrupt, or doesn't align with the snapshot, truncate the WAL.
				if err != nil || ae == nil || ae.pindex != index-1 || n.pindex != ae.pindex {
					if err != nil {
						n.warn("Could not load %d from WAL [%+v]: %v", index, state, err)
					} else {
						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")

View on GitHub (pinned to 3a66a489d2)

Solutions

1. No action needed; truncation self-heals the log to the snapshot boundary
2. Data after the truncation point is re-replicated from the leader
3. Frequent occurrences suggest unclean shutdowns or disk write issues

When it happens

Trigger: Thrown at server/raft.go:594 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/289180f8fab5a954. Report an issue: GitHub.