nats-io/nats-server · error

failed to set consumer %q state: %w

Error message

failed to set consumer %q state: %w

What it means

Emitted during restore after the consumer was successfully recreated: writing the archived delivered/ack/pending state back into the consumer store via setStoreState failed. The consumer exists but its checkpoint state could not be applied, so the restore aborts rather than leave an inconsistent snapshot.

Source

Thrown at server/stream_backup.go:452

		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 {
		hdr, err := tr.Next()
		if err != nil {
			return nil, err
		}
		seq := hdr.Sequence
		if seq == 0 {
			// Sentinel "end of backup" if all fields are zero.
			if hdr.Timestamp == 0 && hdr.HeaderSize == 0 && hdr.PayloadSize == 0 {
				eob = true
				break

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Inspect the wrapped store error; disk full or state-file corruption on the target server are common causes
2. Free space / repair the target server's storage and re-run the restore
3. Remove the partially restored consumer and stream before retrying so state is applied to a clean consumer

When it happens

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