What causes "group node missing" in nats-io/nats-server?

Wait for the raft group node to be initialized on this peer and re-check health

group node missing

Error message

group node missing

What it means

Returned by jetStream.isStreamHealthy for replicated (Replicas > 1) streams when the stream assignment's Raft group has no node (sa.Group.node == nil). The server knows about the group but has not been assigned/started the Raft peer, so replication health cannot be checked.

Source

Thrown at server/jetstream_cluster.go:1046

	if err != nil {
		return errors.New("stream not found")
	}

	msetNode := mset.raftNode()
	mset.cfgMu.RLock()
	replicas := mset.cfg.Replicas
	mset.cfgMu.RUnlock()
	var nrgWerr error
	if node != nil {
		nrgWerr = node.GetWriteErr()
	}
	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")

View on GitHub (pinned to 3a66a489d2)

Solutions

Wait for the raft group node to be initialized on this peer and re-check health
Inspect raft group placement with jsz and confirm this server is an expected peer
If stuck, check meta group logs for placement errors and restart the server to trigger re-init

Defensive patterns

Strategy: retry

Try / catch

if err != nil && strings.Contains(err.Error(), "group node missing") {
    // node not yet placed/initialized; retry after backoff
    time.Sleep(backoff)
    return healthcheck()
}

Prevention

Avoid health checks during replica-count changes or peer reassignments
Use jsz to confirm expected peer placement before probing
Give servers time to initialize raft groups after startup or scaling events

When it happens

Trigger: HEALTHCHECK against an R>1 stream whose raft group node has not yet been created on this server, e.g. during group placement, peer removal/reassignment, or before monitor startup.

Common situations: Scaling a stream's replica count; a peer was just moved to this server; cluster was scaled down/up and assignments are being rebalanced; server recovering its raft state.

Related errors

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