nats-io/nats-server · error

stream assignment not present in clustered mode

Error message

stream assignment not present in clustered mode

What it means

In clustered JetStream, streamSnapshotV2 found no stream assignment (sa == nil) for the stream while including consumers — without the assignment, consumer assignments cannot be derived, so the V2 snapshot fails via the error channel. It indicates missing or inconsistent meta-layer state in the cluster.

Source

Thrown at server/stream_backup.go:141

			path.Join("consumers", scs.Name),
			now.UnixNano(),
			0,
			0,
			int64(len(ssj)),
			ssj,
		)
	}

	// If we aren't including consumers here then make sure the consumer count
	// is set accordingly, this helps on the restore path.
	var consumerAssignments map[string]*consumerAssignment
	var consumerStores []ConsumerStore
	var streamState = *state
	if !includeConsumers {
		streamState.Consumers = 0
	} else if clustered {
		if sa == nil {
			errCh <- errors.New("stream assignment not present in clustered mode")
			return
		}
		js.mu.RLock()
		consumerAssignments = make(map[string]*consumerAssignment, len(sa.consumers))
		for name, ca := range sa.consumers {
			consumerAssignments[name] = ca.copyGroup()
		}
		streamState.Consumers = len(consumerAssignments)
		js.mu.RUnlock()
	} else {
		consumerStores = slices.Collect(store.Consumers())
		streamState.Consumers = len(consumerStores)
	}

	ssj, err := json.Marshal(streamState)
	if err != nil {
		errCh <- err
		return

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Verify the stream has a healthy assignment across meta peers before snapshotting
2. Retry the snapshot once the cluster meta layer has settled
3. Rebalance or recreate the stream if its assignment is permanently lost

When it happens

Trigger: Thrown at server/stream_backup.go:141 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/3d4cb3b0fe554bee. Report an issue: GitHub.