nats-io/nats-server · error

Error decoding message scheduling state: %s

Error message

Error decoding message scheduling state: %s

What it means

A warning logged by recoverMsgSchedulingState() when the persisted message scheduling index file exists but its contents fail to decode (fs.scheduling.decode). The file is treated as unusable: recovery continues with scheduling state reset, and the index is effectively discarded rather than failing stream startup.

Source

Thrown at server/filestore.go:2499

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 {
		schedSeq = fs.state.FirstSeq
	}
	return schedSeq
}

// Grabs last checksum for the named block file.
// Takes into account encryption etc.
func (mb *msgBlock) lastChecksum() []byte {
	f, err := mb.openBlock()
	if err != nil {

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Delete the corrupt scheduling index file so it is regenerated from scratch
2. Check for disk corruption or unexpected writes to the JetStream store directory
3. Verify server version compatibility for the on-disk format

When it happens

Trigger: Thrown at server/filestore.go:2499 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/1225ae7a91ae9628. Report an issue: GitHub.