nats-io/nats-server · error

Error writing peer state file for %q: %v

Error message

Error writing peer state file for %q: %v

What it means

writePeerState failed to persist the peers.idx file (encoded peer membership) for this RAFT group; the error was also latched via setWriteErrLocked. The in-memory n.wps is already updated, so disk state may diverge from memory until a successful rewrite.

Source

Thrown at server/raft.go:5390

		lastIndex: le.Uint64(msg[16:]),
		candidate: string(copyBytes(msg[24 : 24+idLen])),
		reply:     reply,
	}
}

const peerStateFile = "peers.idx"

// Lock should be held.
func (n *raft) writePeerState(ps *peerState) {
	pse := encodePeerState(ps)
	if bytes.Equal(n.wps, pse) {
		return
	}
	// Stamp latest and write the peer state file.
	n.wps = pse
	if err := writePeerState(n.dios, n.sd, ps); err != nil && !n.isClosed() {
		n.setWriteErrLocked(err)
		n.warn("Error writing peer state file for %q: %v", n.group, err)
	}
}

// Writes out our peer state outside of a specific raft context.
func writePeerState(dios *diskIOSemaphore, sd string, ps *peerState) error {
	psf := filepath.Join(sd, peerStateFile)
	if _, err := os.Stat(psf); err != nil && !os.IsNotExist(err) {
		return err
	}
	return writeFileWithSync(dios, psf, encodePeerState(ps), defaultFilePerms)
}

func readPeerState(dios *diskIOSemaphore, sd string) (ps *peerState, err error) {
	dios.acquire()
	buf, err := os.ReadFile(filepath.Join(sd, peerStateFile))
	dios.release()

	if err != nil {

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Check write permissions and disk space in the RAFT store dir
2. The next successful peer-state change will retry the write since wtv-style caching still forces a rewrite on failure
3. Restart after fixing storage so peer state is re-persisted

When it happens

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