nats-io/nats-server · error

failed to add consumer %q: %w

Error message

failed to add consumer %q: %w

What it means

Emitted during restore when mset.addConsumerForRestore fails to create a consumer from the archived config. The wrapped error typically reflects an invalid or conflicting consumer configuration (e.g. durable name collision, invalid filter subject, or limits rejected on the target stream), aborting the restore of that consumer.

Source

Thrown at server/stream_backup.go:442

		var consumer SnapshotConsumerState
		if err := json.Unmarshal(buf, &consumer); err != nil {
			return nil, fmt.Errorf("failed to decode consumer %q state: %w", name, err)
		}
		if consumer.ConsumerConfig == nil {
			return nil, fmt.Errorf("consumer %q is missing config", name)
		}
		if consumer.ConsumerState == nil {
			return nil, fmt.Errorf("consumer %q is missing state", name)
		}
		isEphemeral := !isDurableConsumer(consumer.ConsumerConfig)
		if isEphemeral {
			// Keep ephemerals alive and interested until all messages have
			// been restored, then start their normal inactivity lifecycle.
			consumer.Durable = name
		}
		o, err := mset.addConsumerForRestore(consumer.ConsumerConfig)
		if err != nil {
			return nil, fmt.Errorf("failed to add consumer %q: %w", name, err)
		}
		if isEphemeral {
			ephemerals = append(ephemerals, o)
		}
		restoredConsumers = append(restoredConsumers, o)
		o.mu.Lock()
		err = o.setStoreState(consumer.ConsumerState)
		o.mu.Unlock()
		if err != nil {
			return nil, fmt.Errorf("failed to set consumer %q state: %w", name, err)
		}
	}

	store := mset.store
	lseq := nstate.FirstSeq - 1
	eob := false
	mp := int64(s.getOpts().MaxPayload)
	for {

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Read the wrapped error to identify the config field rejected by consumer creation
2. Check for pre-existing consumers with the same durable name on the target stream and remove them or restore into a clean stream
3. Verify the archived consumer config is supported by the target server version

When it happens

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