nats-io/nats-server · error

Could not load %d from WAL [%+v]: %v

Error message

Could not load %d from WAL [%+v]: %v

What it means

A warning logged during raft node WAL replay when loadEntry(index) fails for a committed-but-not-yet-applied entry identified by its index. It means the write-ahead log entry could not be read or decoded (missing/corrupt entry), so that entry is skipped during replay and upper-layer state may miss it.

Source

Thrown at server/raft.go:592

	if state.Msgs > 0 {
		n.debug("Replaying state of %d entries", state.Msgs)

		// 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
			}

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Inspect the wrapped error and entry details for WAL corruption
2. If the entry is essential, restore the raft WAL from backup or catch up from another peer
3. Consider triggering a snapshot so the WAL range with the gap is no longer needed
4. Check disk health for the JetStream/raft storage directory

When it happens

Trigger: Thrown at server/raft.go:592 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/0c9f3a716a205839. Report an issue: GitHub.