nats-io/nats-server · error

consumer %q is missing config

Error message

consumer %q is missing config

What it means

Validation guard in RestoreStreamV2: a tar entry under consumers/<name> decoded successfully as JSON, but the resulting SnapshotConsumerState has a nil ConsumerConfig. This means the backup archive is malformed or was produced by a different/incompatible version, since a snapshot consumer entry must always carry a config.

Source

Thrown at server/stream_backup.go:429

	for range nstate.Consumers {
		hdr, err := tr.Next()
		if err != nil {
			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)

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Regenerate the backup archive with a matching server version and retry the restore
2. Inspect the consumers/<name> entry in the archive to confirm it contains a non-null config object
3. Verify the archive was not truncated or edited in transit (checksum/transfer integrity)

When it happens

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