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

Retry the health check after a short delay to allow raft node initialization to finish.

consumer node missing

Error message

consumer node missing

What it means

Returned when the consumer's runtime object exists but o.raftNode() is nil — the consumer's own raft node has not been initialized yet, even though the group assignment node exists. The source notes this can happen when the consumer's node is not yet initialized, i.e. the consumer was created but its replicated state machine has not started.

Source

Thrown at server/jetstream_cluster.go:1137

	}

	oNode := o.raftNode()
	rc, _ := o.replica()
	var nrgWerr error
	if node != nil {
		nrgWerr = node.GetWriteErr()
	}
	consumerWerr := o.getWriteErr()
	switch {
	case rc <= 1:
		return nil // No further checks for R=1 consumers

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

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

	case node != oNode:
		mset.mu.RLock()
		accName, streamName := mset.acc.GetName(), mset.cfg.Name
		mset.mu.RUnlock()
		s.Warnf("Detected consumer cluster node skew '%s > %s > %s'", accName, streamName, consumer)
		return errors.New("cluster node skew detected")

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

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

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

	case !node.Healthy():

View on GitHub (pinned to 3a66a489d2)

Solutions

Retry the health check after a short delay to allow raft node initialization to finish.
Inspect server logs for raft/node startup errors and address them (disk, WAL issues).
If stuck indefinitely, restart the server so the consumer's node is recreated during recovery.
Reduce consumer creation bursts so node initialization is not backlogged.

Defensive patterns

Strategy: retry

Try / catch

// Go: allow a warm-up window for node initialization
if err := health(); err != nil && strings.Contains(err.Error(), "consumer node missing") {
    select {
    case <-time.After(3 * time.Second):
        return health() // recheck once initialized
    case <-ctx.Done():
        return ctx.Err()
    }
}

Prevention

Give servers a warm-up period after restart before health-gating
Avoid bursting many replicated consumer creations at once
Watch logs for raft node startup failures
Ensure adequate disk and CPU for raft initialization

When it happens

Trigger: Health check between consumer materialization and raft node start: lookupConsumer succeeded but o.raftNode() is nil — e.g. consumer create in progress, or raft node start deferred/failed after recovery.

Common situations: Polling /jsz?health=true immediately after creating a replicated consumer; server restart where consumer recovery is still initializing nodes; low-resource or heavily loaded servers delaying node start.

Related errors

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