nats-io/nats-server · error

stream write error: %v

Error message

stream write error: %v

What it means

During the stream health check, the stream-level raft/meta write returned an error (streamWerr) — the write affecting the stream's state in its raft group failed. Reported as 'stream write error' wrapping the cause, distinguishing it from the node (nrg) write failure.

Source

Thrown at server/jetstream_cluster.go:1060

	case replicas <= 1:
		return nil // No further checks for R=1 streams

	case node == nil:
		return errors.New("group node missing")

	case msetNode == nil:
		// Can happen when the stream's node is not yet initialized.
		return errors.New("stream node missing")

	case node != msetNode:
		s.Warnf("Detected stream cluster node skew '%s > %s'", acc.GetName(), streamName)
		return errors.New("cluster node skew detected")

	case nrgWerr != nil:
		return fmt.Errorf("node write error: %v", nrgWerr)

	case streamWerr != nil:
		return fmt.Errorf("stream write error: %v", streamWerr)

	case !mset.isMonitorRunning():
		return errors.New("monitor goroutine not running")

	case mset.isCatchingUp():
		return errors.New("stream catching up")

	case !node.Healthy():
		return errors.New("group node unhealthy")

	default:
		return nil
	}
}

// isConsumerHealthy will determine if the consumer is up to date.
// For R1 it will make sure the consunmer is present on this server.
func (js *jetStream) isConsumerHealthy(mset *stream, consumer string, ca *consumerAssignment) error {

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Inspect the wrapped error to identify whether it is storage- or network-related and fix that layer (disk, permissions, connectivity)
2. Verify all replica peers are online and replicating; restore quorum if peers are down
3. Re-run the health check after the cluster stabilizes; transient partition errors self-heal
4. If the stream is stuck mid-restore, restart the restore or recreate the stream from a backup

// check storage health and replica connectivity before health check
if diskUsage(raftDir) > 0.9 { alert("raft dir nearly full") }

func isStreamWriteErr(err error) bool { return strings.HasPrefix(err.Error(), "stream write error") }

if err := healthz(); err != nil && strings.HasPrefix(err.Error(), "stream write error") {
    // inspect wrapped cause: storage vs network; retry after remediation
}

When it happens

Trigger: Replicating or persisting stream state failed during health check (peer offline, quorum loss); storage backend returned an error while writing stream state; stream is mid-restore/migration and its raft group is not accepting writes.

Common situations: FileStorage directory permission or disk-full problems; network partitions isolating replicas; performing health checks immediately after a stream restore or scale-out before replication catches up.

Related errors

• node write error: %v
• stream assignment or group missing
• group node missing
• stream node missing
• cluster node skew detected

AI-assisted analysis of nats-io/nats-server@3a66a489d2 (2026-09-02). Data as JSON: /api/errors/a3c29bd562db865e. Report an issue: GitHub.