nats-io/nats-server · error

Could not find a starting entry for catchup request: %v

Error message

Could not find a starting entry for catchup request: %v

What it means

After the direct loadEntry(start) failed and a loadFirstEntry() fallback was attempted, the leader still could not obtain any starting entry for the catchup request — the log is empty, closed, or unreadable. Catchup cannot proceed from the log.

Source

Thrown at server/raft.go:3805

			}
			n.debug("Snapshot sent, reset first catchup entry to %d", lastIndex)
		}
	}

	ae, err := n.loadEntry(start)
	if err != nil {
		n.warn("Request from follower for entry at index [%d] errored for state %+v - %v", start, state, err)
		if err == ErrStoreEOF {
			// If we are here we are seeing a request for an item beyond our state, meaning we should stepdown.
			n.stepdownLocked(noLeader)
			n.Unlock()
			arPool.Put(ar)
			return
		}
		ae, err = n.loadFirstEntry()
	}
	if err != nil || ae == nil {
		n.warn("Could not find a starting entry for catchup request: %v", err)
		// If we are here we are seeing a request for an item we do not have, meaning we should stepdown.
		// This is possible on a reset of our WAL but the other side has a snapshot already.
		// If we do not stepdown this can cycle.
		n.stepdownLocked(noLeader)
		n.Unlock()
		arPool.Put(ar)
		return
	}
	if ae.pindex != ar.index || ae.pterm != ar.term {
		n.debug("Our first entry [%d:%d] does not match request from follower [%d:%d]", ae.pterm, ae.pindex, ar.term, ar.index)
	}
	// Create a queue for delivering updates from responses.
	indexUpdates := newIPQueue[uint64](n.s, fmt.Sprintf("[ACC:%s] RAFT '%s' indexUpdates", n.accName, n.group))
	indexUpdates.push(ae.pindex)
	n.progress[ar.peer] = indexUpdates
	n.wg.Add(1)
	n.Unlock()
	started := n.s.startGoRoutine(func() {

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Verify the leader actually has entries or a snapshot to serve
2. Check the WAL store for corruption or truncation
3. The follower will be served by a snapshot from a node with sufficient state

When it happens

Trigger: Thrown at server/raft.go:3805 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/4a58f6b6da62568e. Report an issue: GitHub.