{"record":{"id":"619329d248124664","repo":"nats-io/nats-server","slug":"unsupported-consumer-q","errorCode":null,"errorMessage":"unsupported consumer %q","messagePattern":"unsupported consumer %q","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"server/jetstream_cluster.go","lineNumber":6643,"sourceCode":"\n\t// Capture the optional state. We will pass it along if we are a member to apply.\n\t// This is only applicable when restoring a stream with consumers.\n\tstate := ca.State\n\tca.State = nil\n\n\t// Place into our internal map under the stream assignment.\n\t// Ok to replace an existing one, we check on process call below.\n\tsa.consumers[ca.Name] = ca\n\tcc.removeInflightConsumerProposal(accName, stream, consumerName)\n\n\t// If unsupported, we can't register any further.\n\tif ca.unsupported != nil {\n\t\tca.unsupported.setupInfoSub(s, ca)\n\t\ts.Warnf(\"Detected unsupported consumer '%s > %s > %s': %s\", accName, stream, ca.Name, ca.unsupported.reason)\n\n\t\t// Mark stream as unsupported as well\n\t\tif sa.unsupported == nil {\n\t\t\tsa.unsupported = newUnsupportedStreamAssignment(s, sa, fmt.Errorf(\"unsupported consumer %q\", ca.Name))\n\t\t}\n\t\tsa.unsupported.setupInfoSub(s, sa)\n\t\tjs.mu.Unlock()\n\n\t\t// Be conservative by protecting the whole stream, even if just one consumer is unsupported.\n\t\t// This ensures it's safe, even with Interest-based retention where it would otherwise\n\t\t// continue accepting but dropping messages.\n\t\tacc, err := s.lookupOrFetchAccount(accName, isMember)\n\t\tif err != nil {\n\t\t\treturn\n\t\t}\n\t\tmset, err := acc.lookupStream(stream)\n\t\tif err != nil || mset.closed.Load() {\n\t\t\treturn\n\t\t}\n\t\ts.Warnf(\"Stopping unsupported stream '%s > %s'\", accName, stream)\n\t\tmset.stop(false, false)\n\t\treturn","sourceCodeStart":6625,"sourceCodeEnd":6661,"githubUrl":"https://github.com/nats-io/nats-server/blob/3a66a489d262bf89b71a71c955c94920394532f3/server/jetstream_cluster.go#L6625-L6661","documentation":"During consumer assignment recovery, a NATS server detects a consumer config/feature from a newer server version that this server does not support (ca.unsupported is set). The server logs a warning, subscribes for info updates, and marks the parent stream assignment as unsupported with the error `unsupported consumer %q`, so the whole stream is protected from modification rather than operating on partially-understood state.","triggerScenarios":"A server running an older nats-server version joins or restarts in a cluster (or recovers a stream assignment file) where another, newer server created a consumer using newer configuration options or features (e.g. new consumer config fields, priority groups, metadata) that the older binary cannot parse.","commonSituations":"Mixed-version clusters during upgrades; rolling restarts where one node is on an old release; restoring a stream (RA3/mirror/sourced or backup) created by a newer server.","solutions":["Upgrade all servers in the cluster to a version that supports the consumer configuration (>= the version that created the consumer).","Keep server versions homogeneous: complete rolling upgrades promptly and pin the cluster to one release.","If the new consumer is not needed, delete it from the newer server so the old server can take over the stream.","Check the warning log line ('Detected unsupported consumer ...') for the exact unsupported reason."],"exampleFix":"// before: mixed cluster\n$ nats-server -c nats.conf   # v2.9 binary joining v2.10 peers\n// after: upgrade the old node first\n$ nats-server --version && go install github.com/nats-io/nats-server/v2@latest\n$ nats-server -c nats.conf   # all nodes on same version","handlingStrategy":"validation","validationCode":"// compare server versions before forming a cluster\nif serverVersion < minVersionThatCreatedConsumers {\n    upgradeBeforeJoining()\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Keep all servers in a JetStream cluster on the same binary version.","Check `nats server info` versions before joining a node.","Review release notes for new consumer config features before upgrading only part of the cluster.","Watch for 'Detected unsupported consumer' warnings in logs during upgrades."],"tags":["jetstream","cluster","version-compatibility","consumer"],"backgroundTag":"unsupported-consumer-config","analyzedSha":"3a66a489d262bf89b71a71c955c94920394532f3","analyzedAt":"2026-09-02T04:41:54.247Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T15:18:49.778Z"}