nats-io/nats-server · error

couldn't load consumer '%s' state: %s

Error message

couldn't load consumer '%s' state: %s

What it means

Emitted during a non-clustered (single-server) stream snapshot when ConsumerStore.State() fails for a locally tracked consumer. The wrapped error usually comes from the underlying message store (file or memory) and means the consumer's persisted state could not be read, aborting the backup of that consumer's config/state entry.

Source

Thrown at server/stream_backup.go:209

				ci, err := sysRequest[ConsumerInfo](js.srv, clusterConsumerInfoT, sa.Client.serviceAccount(), sa.Config.Name, ca.Name)
				if err != nil || ci == nil {
					errCh <- fmt.Errorf("failed to get consumer state for '%s > %s'", sa.Config.Name, ca.Name)
					return
				}
				if err := writeConsumerMsg(SnapshotConsumerState{
					ConsumerConfig: ca.Config,
					ConsumerState:  consumerStateFromInfo(ci),
				}); err != nil {
					errCh <- err
					return
				}
			}
		} else {
			for _, o := range consumerStores {
				config := o.GetConfig()
				state, err := o.State()
				if err != nil {
					errCh <- fmt.Errorf("couldn't load consumer '%s' state: %s", config.Name, err)
					return
				}
				if err := writeConsumerMsg(SnapshotConsumerState{
					ConsumerConfig: config,
					ConsumerState:  state,
				}); err != nil {
					errCh <- err
					return
				}
			}
		}
	}

	var sm StoreMsg
	for seq := state.FirstSeq - 1; seq < state.LastSeq; {
		if _, seq, err = store.LoadNextMsg(fwcs, true, seq+1, &sm); err != nil {
			if err == ErrStoreEOF {
				break

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Inspect the wrapped error; file-store corruption or a locked state file are typical root causes
2. Run nats stream info / consumer report against the server to surface store-level errors
3. Repair or recover the stream store (e.g. restore from replicas or a prior backup) and re-run the snapshot

When it happens

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