{"record":{"id":"0e5f34d59852c0d5","repo":"nats-io/nats-server","slug":"consumer-assignment-or-group-missing","errorCode":null,"errorMessage":"consumer assignment or group missing","messagePattern":"consumer assignment or group missing","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"server/jetstream_cluster.go","lineNumber":1096,"sourceCode":"func (js *jetStream) isConsumerHealthy(mset *stream, consumer string, ca *consumerAssignment) error {\n\tjs.mu.RLock()\n\tif ca != nil && ca.unsupported != nil {\n\t\tjs.mu.RUnlock()\n\t\treturn nil\n\t}\n\tif mset == nil {\n\t\tjs.mu.RUnlock()\n\t\treturn errors.New(\"stream missing\")\n\t}\n\ts, cc := js.srv, js.cluster\n\tif cc == nil {\n\t\t// Non-clustered mode\n\t\tjs.mu.RUnlock()\n\t\treturn nil\n\t}\n\tif ca == nil || ca.Group == nil {\n\t\tjs.mu.RUnlock()\n\t\treturn errors.New(\"consumer assignment or group missing\")\n\t}\n\t// Surface any persisted assignment-level error (e.g. failed create on this\n\t// peer) so the health check reflects the broken state instead of falling\n\t// through to runtime-only checks.\n\tif ca.err != nil {\n\t\terr := ca.err\n\t\tjs.mu.RUnlock()\n\t\treturn fmt.Errorf(\"consumer assignment error: %w\", err)\n\t}\n\tcreated := ca.Created\n\tnode := ca.Group.node\n\tjs.mu.RUnlock()\n\n\t// Check if not running at all.\n\to := mset.lookupConsumer(consumer)\n\tif o == nil {\n\t\tif time.Since(created) < 5*time.Second {\n\t\t\t// No further checks, consumer is not available yet but should be soon.","sourceCodeStart":1078,"sourceCodeEnd":1114,"githubUrl":"https://github.com/nats-io/nats-server/blob/3a66a489d262bf89b71a71c955c94920394532f3/server/jetstream_cluster.go#L1078-L1114","documentation":"Thrown by isConsumerHealthy when, in clustered mode, there is no consumerAssignment (ca) or the assignment has no raft Group — i.e. the server knows a consumer should exist but has no cluster assignment record for it. This means the meta layer has not yet assigned (or has already removed) the consumer's placement for this server, so its raft group and health cannot be evaluated.","triggerScenarios":"Health check runs on a server with js.cluster != nil while ca is nil for the requested consumer, or ca.Group == nil — e.g. consumer API request accepted by the leader but the assignment has not propagated to this peer yet, or the assignment was purged during meta recovery.","commonSituations":"Right after adding a consumer with Replicas > 1 while a replica is still syncing; after a split-brain or meta-controller election where assignments are being re-proposed; during initial cluster formation when /jsz?health=true is polled too aggressively.","solutions":["Wait for meta-group convergence: verify all peers see the consumer assignment (jsz API on each server) and re-check health.","Confirm the meta/raft group is healthy (no split brain); fix connectivity between cluster peers (routes) if elections are flapping.","If the consumer should exist, re-issue the consumer create request once the cluster is stable.","Poll the health endpoint less aggressively during topology changes; the condition is usually transient."],"exampleFix":null,"handlingStrategy":"retry","validationCode":"// Confirm the consumer assignment is visible before health checks\ninfo, err := js.ConsumerInfo(stream, consumer)\nif err != nil || info == nil {\n    // assignment not yet propagated; wait\n}\n","typeGuard":null,"tryCatchPattern":"// Go: back off and retry while cluster converges\nerr := healthCheck()\nfor i := 0; err != nil && strings.Contains(err.Error(), \"assignment or group missing\") && i < 5; i++ {\n    time.Sleep(time.Duration(1<<i) * time.Second)\n    err = healthCheck()\n}","preventionTips":["Wait for cluster convergence before health-polling after consumer creation","Keep meta group connectivity stable (routes) to avoid re-proposals","Don't poll health aggressively during rolling restarts","Ensure all peers run compatible NATS server versions"],"tags":["jetstream","nats","clustering","raft"],"backgroundTag":"jetstream-health-check-failed","analyzedSha":"3a66a489d262bf89b71a71c955c94920394532f3","analyzedAt":"2026-09-02T04:41:54.247Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}