{"record":{"id":"72713662b7860649","repo":"nats-io/nats-server","slug":"unable-to-delete-session-q-record-at-sequence-v","errorCode":null,"errorMessage":"unable to delete session %q record at sequence %v: %v","messagePattern":"unable to delete session %q record at sequence (.+?): (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"server/mqtt.go","lineNumber":3499,"sourceCode":"\tfor _, dur := range durs {\n\t\tif _, err := sess.jsa.deleteConsumer(mqttStreamName, dur, noWait); isErrorOtherThan(err, JSConsumerNotFoundErr) {\n\t\t\treturn fmt.Errorf(\"unable to delete consumer %q for session %q: %v\", dur, sess.id, err)\n\t\t}\n\t}\n\tif pubRelDur != _EMPTY_ {\n\t\t_, err := sess.jsa.deleteConsumer(mqttOutStreamName, pubRelDur, noWait)\n\t\tif isErrorOtherThan(err, JSConsumerNotFoundErr) {\n\t\t\treturn fmt.Errorf(\"unable to delete consumer %q for session %q: %v\", pubRelDur, sess.id, err)\n\t\t}\n\t}\n\n\tif seq > 0 {\n\t\terr := sess.jsa.deleteMsg(mqttSessStreamName, seq, !noWait)\n\t\t// Ignore the various errors indicating that the message (or sequence)\n\t\t// is already deleted, can happen in a cluster.\n\t\tif isErrorOtherThan(err, JSSequenceNotFoundErrF) {\n\t\t\tif isErrorOtherThan(err, JSStreamMsgDeleteFailedF) || !strings.Contains(err.Error(), ErrStoreMsgNotFound.Error()) {\n\t\t\t\treturn fmt.Errorf(\"unable to delete session %q record at sequence %v: %v\", id, seq, err)\n\t\t\t}\n\t\t}\n\t}\n\treturn nil\n}\n\n// This will update the session record for this client in the account's MQTT\n// sessions stream if the session had any change in the subscriptions.\n//\n// Runs from the client's readLoop.\n// Lock not held on entry, but session is in the locked map.\nfunc (sess *mqttSession) update(filters []*mqttFilter, add bool) error {\n\t// Evaluate if we need to persist anything.\n\tvar needUpdate bool\n\tfor _, f := range filters {\n\t\tif add {\n\t\t\tif f.qos == mqttSubAckFailure {\n\t\t\t\tcontinue","sourceCodeStart":3481,"sourceCodeEnd":3517,"githubUrl":"https://github.com/nats-io/nats-server/blob/3a66a489d262bf89b71a71c955c94920394532f3/server/mqtt.go#L3481-L3517","documentation":"Wraps an error from deleting the session's persisted record message in the '$MQTT.sess' stream by sequence. Sequence-not-found and msg-delete-failed-with-store-msg-not-found are deliberately ignored (benign in a cluster); anything else fails the cleanup.","triggerScenarios":"sess.jsa.deleteMsg(mqttSessStreamName, seq, !noWait) returns an error that is neither JSSequenceNotFoundErrF nor JSStreamMsgDeleteFailedF combined with ErrStoreMsgNotFound — e.g. permissions, API error, timeout, or stream unavailable.","commonSituations":"JetStream unavailable during session replacement (new CONNECT taking over a session); cluster instability; stream permission or internal API errors; server version mismatch in cluster.","solutions":["Check JetStream health and that '$MQTT.sess' message deletion is permitted","Retry the CONNECT once the cluster is stable","Upgrade servers to consistent versions","Inspect the wrapped cause for the precise JetStream API error"],"exampleFix":"// before\n// session replace fails deleting old record\n// after\n// restore JetStream quorum then reconnect; verify: nats stream info $MQTT.sess\nnull","handlingStrategy":"retry","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n  await mqttConnect() // replaces previous session\n} catch (e) {\n  if (String(e).includes('unable to delete session')) {\n    await waitForJetStreamHealthy()\n    await mqttConnect()\n  } else { throw e }\n}","preventionTips":["Verify deletion is healthy on '$MQTT.sess' after upgrades","Keep servers version-consistent in the cluster","Treat session-not-found style errors as benign (server already does) and only escalate others","Monitor wrapped cause errors in server logs"],"tags":["mqtt","jetstream","persistence","delete"],"backgroundTag":"jetstream-msg-delete-failed","analyzedSha":"3a66a489d262bf89b71a71c955c94920394532f3","analyzedAt":"2026-09-02T04:41:54.247Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}