nats-io/nats-server · error

Message scheduling state is outdated; attempting to recover

Error message

Message scheduling state is outdated; attempting to recover using linear scan (seq %d to %d)

What it means

On recovery, the message-scheduling state (e.g. for delayed/paused message delivery) is outdated relative to the stored messages. The store will re-derive scheduling via a linear scan of the message range rather than trusting the stale state file.

Source

Thrown at server/filestore.go:2349

	}

	// If only sources need recovering, then we can optimize to a backward scan.
	if sourcesRecover && !ttlRecover && !schedRecover {
		if fs.state.Msgs > 0 && sourcesSeq <= fs.state.LastSeq {
			fs.warn("Sourcing state is outdated; attempting to recover using backward scan (seq %d to %d)", sourcesSeq, fs.state.LastSeq)
			if err := fs.recoverSourcesBackwardScan(sourcesSeq, sourcesScan); err != nil {
				return err
			}
		}
		return nil
	}

	if fs.state.Msgs > 0 && scanSeq <= fs.state.LastSeq {
		if ttlRecover && ttlSeq <= fs.state.LastSeq {
			fs.warn("TTL state is outdated; attempting to recover using linear scan (seq %d to %d)", ttlSeq, fs.state.LastSeq)
		}
		if schedRecover && schedSeq <= fs.state.LastSeq {
			fs.warn("Message scheduling state is outdated; attempting to recover using linear scan (seq %d to %d)", schedSeq, fs.state.LastSeq)
		}
		if sourcesRecover && sourcesSeq <= fs.state.LastSeq {
			fs.warn("Sourcing state is outdated; attempting to recover using linear scan (seq %d to %d)", sourcesSeq, fs.state.LastSeq)
		}
		// Only consider sources that need recovering.
		update := func(iName string, sseq uint64, ident string) {
			if _, ok := sourcesScan[iName]; !ok {
				return
			}
			if sss, ok := fs.sources[iName]; ok {
				sss.Seq, sss.Ident = sseq, ident
			}
		}
		var (
			mb     *msgBlock
			sm     StoreMsg
			mblseq uint64
		)

View on GitHub (pinned to 3a66a489d2)

Solutions

  1. No action needed; the scan rebuilds scheduling state automatically
  2. Avoid unclean shutdowns which leave state files stale
  3. Expect a one-time startup cost on large streams
Defensive patterns

Strategy: fallback

When it happens

Trigger: Thrown at server/filestore.go:2349 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/5a14fb29201171b2. Report an issue: GitHub.