nats-io/nats-server · error

failed to activate consumer %q: %w

Error message

failed to activate consumer %q: %w

What it means

After all messages are restored, the deferred block completes each restored consumer via o.completeRestore(), which activates the durable/ephemeral consumer in the server. A failure here is wrapped as 'failed to activate consumer <name>' and returned (if no earlier error), with a server warning. The stream may restore fine but the consumer is left inactive.

Source

Thrown at server/stream_backup.go:404

	}()

	// Start off at the right sequence number. This is important in particular
	// when the backup contains no messages or would restore to no interest.
	if _, err = mset.store.Compact(nstate.FirstSeq); err != nil {
		return nil, fmt.Errorf("error purging stream: %w", err)
	}

	var restoredConsumers, ephemerals []*consumer
	defer func() {
		// Consumers must be unconditionally converted and completed, otherwise
		// a partial restore that fails midway through can leave assets that are
		// unusable.
		for _, o := range ephemerals {
			o.switchToEphemeral()
		}
		for _, o := range restoredConsumers {
			if err := o.completeRestore(); err != nil {
				if err = fmt.Errorf("failed to activate consumer %q: %w", o.name, err); retErr == nil {
					retErr = err
				}
				s.Warnf("JetStream stream restore for '%s > %s' failed to activate consumers: %v", a.Name, cfg.Name, err)
			}
		}
	}()
	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)

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Read the wrapped cause and the 'failed to activate consumers' server warning to identify which consumer and why
2. Check account/JS consumer limits (max_consumers) and cluster health; raise limits or restore with the cluster stable
3. Delete the offending consumer from the partially restored stream and restore again, or restore with the stream's consumers stripped if they are not needed
4. Retry the whole restore after ensuring the server is not shutting down and quorum exists

if accountConsumers(acc) + nstate.Consumers > maxConsumers(acc) {
    return fmt.Errorf("not enough consumer headroom for restore")
}

_, err := acc.RestoreStreamV2(cfg, r)
if err != nil {
    if strings.Contains(err.Error(), "failed to activate consumer") {
        // delete partial stream/consumers, wait for cluster quorum, retry once
    }
    return err
}

When it happens

Trigger: o.completeRestore() fails for a consumer in the snapshot: internal consumer activation error — e.g. the consumer's Raft/group setup fails in clustered mode, the store rejects the consumer state, or the server is shutting down / account consumer limits are exceeded during activation.

Common situations: Restoring consumers into a clustered server where the consumer group cannot form a quorum; account hit max consumer limits; ephemeral consumer conversion (switchToEphemeral) racing with client absence; corrupted consumer state in the snapshot conflicting with current server invariants.

Related errors

• failed to activate stream %q: %w
• expected consumer, found %q
• failed to read consumer %q state: %w
• failed to decode consumer %q state: %w
• max_request_batch must be set if it's JetStream limits are s

AI-assisted analysis of nats-io/nats-server@3a66a489d2 (2026-09-02). Data as JSON: /api/errors/cbce73dbeaa08cee. Report an issue: GitHub.