{"record":{"id":"cbce73dbeaa08cee","repo":"nats-io/nats-server","slug":"failed-to-activate-consumer-q-w","errorCode":null,"errorMessage":"failed to activate consumer %q: %w","messagePattern":"failed to activate consumer %q: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"server/stream_backup.go","lineNumber":404,"sourceCode":"\t}()\n\n\t// Start off at the right sequence number. This is important in particular\n\t// when the backup contains no messages or would restore to no interest.\n\tif _, err = mset.store.Compact(nstate.FirstSeq); err != nil {\n\t\treturn nil, fmt.Errorf(\"error purging stream: %w\", err)\n\t}\n\n\tvar restoredConsumers, ephemerals []*consumer\n\tdefer func() {\n\t\t// Consumers must be unconditionally converted and completed, otherwise\n\t\t// a partial restore that fails midway through can leave assets that are\n\t\t// unusable.\n\t\tfor _, o := range ephemerals {\n\t\t\to.switchToEphemeral()\n\t\t}\n\t\tfor _, o := range restoredConsumers {\n\t\t\tif err := o.completeRestore(); err != nil {\n\t\t\t\tif err = fmt.Errorf(\"failed to activate consumer %q: %w\", o.name, err); retErr == nil {\n\t\t\t\t\tretErr = err\n\t\t\t\t}\n\t\t\t\ts.Warnf(\"JetStream stream restore for '%s > %s' failed to activate consumers: %v\", a.Name, cfg.Name, err)\n\t\t\t}\n\t\t}\n\t}()\n\tfor range nstate.Consumers {\n\t\thdr, err := tr.Next()\n\t\tif err != nil {\n\t\t\treturn nil, err\n\t\t}\n\t\tname, found := strings.CutPrefix(hdr.Name, \"consumers/\")\n\t\tif !found {\n\t\t\treturn nil, fmt.Errorf(\"expected consumer, found %q\", hdr.Name)\n\t\t}\n\t\tbuf, err := io.ReadAll(tr)\n\t\tif err != nil {\n\t\t\treturn nil, fmt.Errorf(\"failed to read consumer %q state: %w\", name, err)","sourceCodeStart":386,"sourceCodeEnd":422,"githubUrl":"https://github.com/nats-io/nats-server/blob/3a66a489d262bf89b71a71c955c94920394532f3/server/stream_backup.go#L386-L422","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Read the wrapped cause and the 'failed to activate consumers' server warning to identify which consumer and why","Check account/JS consumer limits (max_consumers) and cluster health; raise limits or restore with the cluster stable","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","Retry the whole restore after ensuring the server is not shutting down and quorum exists"],"exampleFix":null,"handlingStrategy":"retry","validationCode":"if accountConsumers(acc) + nstate.Consumers > maxConsumers(acc) {\n    return fmt.Errorf(\"not enough consumer headroom for restore\")\n}","typeGuard":null,"tryCatchPattern":"_, err := acc.RestoreStreamV2(cfg, r)\nif err != nil {\n    if strings.Contains(err.Error(), \"failed to activate consumer\") {\n        // delete partial stream/consumers, wait for cluster quorum, retry once\n    }\n    return err\n}","preventionTips":["Check max_consumers account limits against the snapshot's consumer count","Ensure cluster quorum is healthy so consumer groups can form","Restore when the server is not shutting down","Drop unnecessary consumers from the snapshot before restoring"],"tags":["jetstream","stream-restore","consumer","activation"],"backgroundTag":"consumer-activation-failed","analyzedSha":"3a66a489d262bf89b71a71c955c94920394532f3","analyzedAt":"2026-09-02T04:41:54.247Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}