{"record":{"id":"dda20d207f53fca0","repo":"nats-io/nats-server","slug":"consumer-not-found","errorCode":null,"errorMessage":"consumer not found","messagePattern":"consumer not found","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"server/jetstream_cluster.go","lineNumber":1118,"sourceCode":"\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.\n\t\t\t// We'll start erroring once we're sure this consumer is actually broken.\n\t\t\treturn nil\n\t\t}\n\t\treturn errors.New(\"consumer not found\")\n\t}\n\n\toNode := o.raftNode()\n\trc, _ := o.replica()\n\tvar nrgWerr error\n\tif node != nil {\n\t\tnrgWerr = node.GetWriteErr()\n\t}\n\tconsumerWerr := o.getWriteErr()\n\tswitch {\n\tcase rc <= 1:\n\t\treturn nil // No further checks for R=1 consumers\n\n\tcase node == nil:\n\t\treturn errors.New(\"group node missing\")\n\n\tcase oNode == nil:\n\t\t// Can happen when the consumer's node is not yet initialized.","sourceCodeStart":1100,"sourceCodeEnd":1136,"githubUrl":"https://github.com/nats-io/nats-server/blob/3a66a489d262bf89b71a71c955c94920394532f3/server/jetstream_cluster.go#L1100-L1136","documentation":"isConsumerHealthy returns this when the consumer assignment exists (older than the 5s grace window) but no local consumer object (*consumer) can be found on this server (mset.lookupConsumer(consumer) returned nil). It means the consumer should be materialized on this server but its runtime state never appeared — a real, persistent gap between the cluster assignment and local state.","triggerScenarios":"Health check on a non-leader or leader where lookupConsumer(name) is nil and ca.Created is more than 5 seconds in the past — e.g. consumer creation failed locally, the asset recovery skipped it, or the consumer was deleted on the leader without the deletion propagating.","commonSituations":"A consumer added with replicas>1 whose creation failed on some peers; server restarted into a state where the assignment exists in the meta layer but the filestore consumer state is missing/corrupt; deleting a consumer while a health check runs after the 5s grace period.","solutions":["Compare `nats consumer info <stream> <consumer>` against the server's local consumers; if absent but assigned, restart the server to force asset recovery.","Check server logs at startup for consumer recovery errors (filestore corruption, permission issues) and fix the underlying cause.","If the consumer is genuinely gone, delete and recreate it so assignment and runtime state converge.","Check filestore directory for the consumer's directory; restore from backup or remove stale meta state if corrupted."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"// Check the consumer actually exists before health or operations\n_, err := js.ConsumerInfo(streamName, consumerName)\nif err != nil {\n    // consumer genuinely missing: recreate it\n    js.AddConsumer(streamName, &nats.ConsumerConfig{Name: consumerName, ...})\n}\n","typeGuard":null,"tryCatchPattern":"// Go: surface persistent absence, do not retry indefinitely\nif err := health(); err != nil && strings.Contains(err.Error(), \"consumer not found\") {\n    return fmt.Errorf(\"consumer %q permanently missing on server: recreate or recover\", consumerName)\n}","preventionTips":["Verify filestore directories are intact before restarts","Use additive delete/recreate flows rather than in-place consumer surgery","Check startup logs for consumer recovery errors","Monitor consumer presence after every consumer create (replicas>1)"],"tags":["jetstream","nats","consumers","clustering"],"backgroundTag":"jetstream-consumer-not-found","analyzedSha":"3a66a489d262bf89b71a71c955c94920394532f3","analyzedAt":"2026-09-02T04:41:54.247Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}