nats-io/nats-server · error

File system permission denied when flushing stream state, di

Error message

File system permission denied when flushing stream state, disabling JetStream: %v

What it means

A warning logged by fileStore.flushStreamStateLoop() when the periodic writeFullState() of a stream's state fails with a permission error. JetStream for that stream is then disabled because the store can no longer persist state safely; the underlying directory or state file is not writable by the server process.

Source

Thrown at server/filestore.go:12131

// This go routine periodically writes out our full stream state index.
func (fs *fileStore) flushStreamStateLoop(qch, done chan struct{}) {
	// Signal we are done on exit.
	defer close(done)

	// Make sure we do not try to write these out too fast.
	// Spread these out for large numbers on a server restart.
	const writeThreshold = 2 * time.Minute
	writeJitter := time.Duration(mrand.Int63n(int64(30 * time.Second)))
	t := time.NewTicker(writeThreshold + writeJitter)
	defer t.Stop()

	for {
		select {
		case <-t.C:
			err := fs.writeFullState()
			if isPermissionError(err) && fs.srv != nil {
				fs.warn("File system permission denied when flushing stream state, disabling JetStream: %v", err)
				// messages in block cache could be lost in the worst case.
				// In the clustered mode it is very highly unlikely as a result of replication.
				fs.srv.ShutdownJetStream()
				return
			}

		case <-qch:
			return
		}
	}
}

// Helper since unixnano of zero time undefined.
func timestampNormalized(t time.Time) int64 {
	if t.IsZero() {
		return 0
	}
	return t.UnixNano()

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Fix permissions/ownership on the stream's store directory so the server user can write
2. Check for the directory being read-only (mounted ro, disk full-quota, ransomware protection)
3. Restore write access and restart the server or recreate the stream

When it happens

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