{"record":{"id":"db9ea80a428e0e8f","repo":"nats-io/nats-server","slug":"loading-session-record-w","errorCode":null,"errorMessage":"loading session record: %w","messagePattern":"loading session record: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"server/mqtt.go","lineNumber":3163,"sourceCode":"\n// Creates the session stream (limit msgs of 1) for this client ID if it does\n// not already exist. If it exists, recover the single record to rebuild the\n// state of the session. If there is a session record but this session is not\n// registered in the runtime of this server, then a request is made to the\n// owner to close the client associated with this session since specification\n// [MQTT-3.1.4-2] specifies that if the ClientId represents a Client already\n// connected to the Server then the Server MUST disconnect the existing client.\n//\n// Runs from the client's readLoop.\n// Lock not held on entry, but session is in the locked map.\nfunc (as *mqttAccountSessionManager) createOrRestoreSession(clientID string, opts *Options) (*mqttSession, bool, error) {\n\tjsa := &as.jsa\n\n\thash := getHash(clientID)\n\tsmsg, err := jsa.loadSessionMsg(as.domainTk, hash)\n\tif err != nil {\n\t\tif isErrorOtherThan(err, JSNoMessageFoundErr) {\n\t\t\treturn nil, false, fmt.Errorf(\"loading session record: %w\", err)\n\t\t}\n\t\t// Message not found, so reate the session...\n\t\t// Create a session and indicate that this session did not exist.\n\t\tsess := mqttSessionCreate(jsa, clientID, hash, 0, opts)\n\t\tsess.domainTk = as.domainTk\n\t\treturn sess, false, nil\n\t}\n\t// We need to recover the existing record now.\n\tps := &mqttPersistedSession{}\n\tif err := json.Unmarshal(smsg.Data, ps); err != nil {\n\t\treturn nil, false, fmt.Errorf(\"unmarshal of session record at sequence %v: %w\", smsg.Sequence, err)\n\t}\n\tif ps.ID != clientID {\n\t\treturn nil, false, errMQTTSessionCollision\n\t}\n\tfor sid, cc := range ps.Cons {\n\t\tif cc == nil {\n\t\t\tdelete(ps.Cons, sid)","sourceCodeStart":3145,"sourceCodeEnd":3181,"githubUrl":"https://github.com/nats-io/nats-server/blob/3a66a489d262bf89b71a71c955c94920394532f3/server/mqtt.go#L3145-L3181","documentation":"Wraps a JetStream error that occurred while loading a persisted MQTT session record from the '$MQTT.sess' stream via loadSessionMsg. Only returned when the error is something OTHER than 'message not found' (not-found leads to session creation instead), so this signals real JetStream/storage trouble.","triggerScenarios":"jsa.loadSessionMsg fails with a non-JSNoMessageFoundErr error during session lookup — e.g. JetStream stream unavailable, timeout, API error, or storage failure when fetching the session message for the client ID hash.","commonSituations":"JetStream not running or degraded; '$MQTT.sess' stream limits misconfigured; cluster quorum lost; disk errors on the server storing the session.","solutions":["Check JetStream health (server /jsz, stream state for $MQTT.sess)","Retry the CONNECT once JetStream is available","Verify stream retention/limits have not discarded needed records unexpectedly","Inspect server logs for the wrapped underlying error (%w cause)"],"exampleFix":"// before\n// CONNECT fails with opaque JetStream error\n// after\n// start/restart JetStream, ensure stream $MQTT.sess exists: nats stream info $MQTT.sess\nnull","handlingStrategy":"retry","validationCode":"// Pre-check JetStream availability before connecting\nconst js = await fetch('http://monitor:8222/jsz').then(r => r.json())\nif (!js || !js.config) throw new Error('JetStream not available')","typeGuard":null,"tryCatchPattern":"try {\n  await mqttConnect()\n} catch (e) {\n  if (String(e).includes('loading session record')) {\n    await waitForJetStreamHealthy()\n    await mqttConnect()\n  } else { throw e }\n}","preventionTips":["Monitor JetStream health (/jsz) and alert on degradation","Ensure the $MQTT.sess stream exists with sane limits","Keep cluster quorum healthy before rolling MQTT clients","Read the wrapped cause (%w) in server logs to identify the root JetStream error"],"tags":["mqtt","jetstream","persistence"],"backgroundTag":"jetstream-load-failed","analyzedSha":"3a66a489d262bf89b71a71c955c94920394532f3","analyzedAt":"2026-09-02T04:41:54.247Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}