nats-io/nats-server · error

Recovering message scheduling state from index errored: %v

Error message

Recovering message scheduling state from index errored: %v

What it means

A warning logged (not returned) by recoverMsgSchedulingState() during stream recovery when reading the message scheduling index file fails with an error other than not-exist (e.g. I/O or permission error). The store continues recovery without the persisted scheduling state, falling back to rebuilding it in memory; the sequence state may be less precise.

Source

Thrown at server/filestore.go:2489

		}
	}

	if ttlseq < fs.state.FirstSeq {
		ttlseq = fs.state.FirstSeq
	}
	return ttlseq
}

// Lock should be held.
func (fs *fileStore) recoverMsgSchedulingState() uint64 {
	// See if we have a schedule index file.
	fs.dios.acquire()
	fn := filepath.Join(fs.fcfg.StoreDir, msgDir, msgSchedulingStreamStateFile)
	buf, err := os.ReadFile(fn)
	fs.dios.release()

	if err != nil && !os.IsNotExist(err) {
		fs.warn("Recovering message scheduling state from index errored: %v", err)
	}

	fs.scheduling = newMsgScheduling(fs.runMsgScheduling)
	fs.scheduling.paused = fs.recovering

	var schedSeq uint64
	if err == nil {
		schedSeq, err = fs.scheduling.decode(buf)
		if err != nil {
			fs.warn("Error decoding message scheduling state: %s", err)
			// Remove the file, and reset collected state (if any).
			_ = os.Remove(fn)
			fs.scheduling = newMsgScheduling(fs.runMsgScheduling)
			fs.scheduling.paused = fs.recovering
		}
	}

	if schedSeq < fs.state.FirstSeq {

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Inspect the wrapped OS error for disk or permission problems on the stream's store directory
2. Fix underlying I/O issues and restart the server to recover scheduling state correctly
3. If the index file is corrupt, remove it; the scheduling state will be rebuilt

When it happens

Trigger: Thrown at server/filestore.go:2489 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/5434a7805f1b5b74. Report an issue: GitHub.