nats-io/nats-server · error

node write error: %v

Error message

node write error: %v

What it means

During the stream portion of a JetStream health check, the node/raft group write returned an error (nrgWerr) when checking or updating the stream's raft node state. The health check reports 'node write error' with the underlying error, indicating the stream's meta/node raft group cannot be written to — typically an unavailable quorum or a shutdown raft group.

Source

Thrown at server/jetstream_cluster.go:1057

	}
	streamWerr := mset.getWriteErr()
	switch {
	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
	}
}

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Restore raft quorum: restart or repair the missing peers so the stream's raft group has a majority
2. Check server logs and disk space/free space on raft log directories on all peers
3. If the stream is being deleted/replaced, wait for the operation to finish and re-run health checks
4. As a last resort, use the stream reset/recovery tooling (or recreate the stream) if the raft state is irrecoverably corrupt

// before probing health, verify quorum peers are reachable
for _, peer := range clusterPeers { if !reachable(peer) { skipHealthCheck(peer) } }

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

if err := healthz(); err != nil && strings.HasPrefix(err.Error(), "node write error") {
    // quorum/raft issue: back off and retry after peers recover
}

When it happens

Trigger: Raft group for the stream has no quorum (majority of peers down or partitioned); raft group already shut down (server stopping or stream being deleted); disk I/O failure on the raft log preventing writes; calling health checks during leader transitions.

Common situations: Cluster degraded after node loss so raft writes fail; snapshot/compaction issues or full disk on peers; health endpoints probed by load balancers while the cluster is recovering.

Related errors

• stream write error: %v
• JS_CONSUMER_OFFLINE
• stream assignment or group missing
• group node missing
• stream node missing

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