nats-io/nats-server · error

consumer %q is missing state

Error message

consumer %q is missing state

What it means

Validation guard in RestoreStreamV2: the decoded SnapshotConsumerState for consumers/<name> has a non-nil config but a nil ConsumerState. The archive entry is incomplete — every snapshot consumer entry must include both a config and a state — so the consumer cannot be recreated with correct delivered/ack floors.

Source

Thrown at server/stream_backup.go:432

			return nil, err
		}
		name, found := strings.CutPrefix(hdr.Name, "consumers/")
		if !found {
			return nil, fmt.Errorf("expected consumer, found %q", hdr.Name)
		}
		buf, err := io.ReadAll(tr)
		if err != nil {
			return nil, fmt.Errorf("failed to read consumer %q state: %w", name, err)
		}
		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()

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Re-create the backup with the same server version that produced the original stream
2. Inspect the consumers/<name> JSON entry and confirm the state field is present and non-null
3. Ensure the archive was not truncated mid-entry during creation or transfer

When it happens

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