nats-io/nats-server · error

Stream state encountered internal inconsistency on write

Error message

Stream state encountered internal inconsistency on write

What it means

While persisting the stream state file, the in-memory fs.state diverged from the state aggregated from message blocks (trackingStatesEqual returned false). The store rebuilds its state from the blocks and returns errCorruptState rather than writing inconsistent accounting to disk.

Source

Thrown at server/filestore.go:12358

	fn := filepath.Join(fs.fcfg.StoreDir, msgDir, streamStreamStateFile)

	// Need to have our own hasher here, as under a read lock we can't mutate the
	// fs.hh safely.
	key := sha256.Sum256([]byte(fs.cfg.Name))
	hh, _ := highwayhash.NewDigest64(key[:])
	hh.Write(buf)
	buf = hh.Sum(buf)

	// Snapshot prior dirty count.
	priorDirty := fs.dirty

	statesEqual := trackingStatesEqual(&fs.state, &mstate)
	// Release lock.
	fs.mu.RUnlock()

	// Check consistency here.
	if !statesEqual {
		fs.warn("Stream state encountered internal inconsistency on write")
		// Rebuild our fs state from the mb state.
		fs.rebuildState(nil)
		return errCorruptState
	}

	if cap(buf) > sz {
		fs.debug("WriteFullState reallocated from %d to %d", sz, cap(buf))
	}

	// Only warn about construction time since file write not holding any locks.
	if took := time.Since(start); took > time.Minute {
		fs.warn("WriteFullState took %v (%d bytes)", took.Round(time.Millisecond), len(buf))
	}

	// Write our update index.db
	// Protect with dios.
	fs.dios.acquire()
	err := os.WriteFile(fn, buf, defaultFilePerms)

View on GitHub (pinned to 3a66a489d2)

Solutions

1. The automatic rebuildState reconciles the counters; verify stream info afterwards
2. Run message integrity checks on the stream
3. If it recurs, suspect a bug or failing storage and report with logs

When it happens

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