{"record":{"id":"564077b0b1f283e5","repo":"nats-io/nats-server","slug":"create-sessions-stream-for-account-q-v","errorCode":null,"errorMessage":"create sessions stream for account %q: %v","messagePattern":"create sessions stream for account %q: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"server/mqtt.go","lineNumber":1428,"sourceCode":"\t\treturn si, nil\n\t}\n\n\tif si, err := lookupStream(mqttSessStreamName, \"sessions\"); err != nil {\n\t\treturn nil, err\n\t} else if si == nil {\n\t\t// Create the stream for the sessions.\n\t\tcfg := &StreamConfig{\n\t\t\tName:       mqttSessStreamName,\n\t\t\tSubjects:   []string{mqttSessStreamSubjectPrefix + as.domainTk + \">\"},\n\t\t\tStorage:    FileStorage,\n\t\t\tRetention:  LimitsPolicy,\n\t\t\tReplicas:   replicas,\n\t\t\tMaxMsgsPer: 1,\n\t\t}\n\t\tif _, created, err := jsa.createStream(cfg); err == nil && created {\n\t\t\tas.transferUniqueSessStreamsToMuxed(s)\n\t\t} else if isErrorOtherThan(err, JSStreamNameExistErr) {\n\t\t\treturn nil, fmt.Errorf(\"create sessions stream for account %q: %v\", accName, err)\n\t\t}\n\t}\n\n\tif si, err := lookupStream(mqttStreamName, \"messages\"); err != nil {\n\t\treturn nil, err\n\t} else if si == nil {\n\t\t// Create the stream for the messages.\n\t\tcfg := &StreamConfig{\n\t\t\tName:      mqttStreamName,\n\t\t\tSubjects:  []string{mqttStreamSubjectPrefix + \">\"},\n\t\t\tStorage:   FileStorage,\n\t\t\tRetention: InterestPolicy,\n\t\t\tReplicas:  replicas,\n\t\t}\n\t\tif _, _, err := jsa.createStream(cfg); isErrorOtherThan(err, JSStreamNameExistErr) {\n\t\t\treturn nil, fmt.Errorf(\"create messages stream for account %q: %v\", accName, err)\n\t\t}\n\t}","sourceCodeStart":1410,"sourceCodeEnd":1446,"githubUrl":"https://github.com/nats-io/nats-server/blob/3a66a489d262bf89b71a71c955c94920394532f3/server/mqtt.go#L1410-L1446","documentation":"When the account's muxed MQTT sessions stream does not exist (or needs upgrading for mqtt.SessionReplicas > 1), the server attempts to create it with MaxMsgsPer=1 and the configured replicas. If creation fails with any error other than JSStreamNameExistErr (a benign race where another server created it first), this wrapped error is returned and the MQTT CONNECT fails.","triggerScenarios":"jsa.createStream(cfg) for the '<account>-mqtt-sessions' stream returns an error that is not JSStreamNameExistErr — e.g. insufficient JS resources, invalid config for the account tier, or a JS API error. Triggered in mqttJSStreamConfig when setting up the sessions stream.","commonSituations":"Account JS tier limits (max streams, storage) exceeded; upgrading to MQTT.StreamReplicas>1 on an account whose existing stream can't be replaced; JS disabled; permissions errors.","solutions":["Read the inner error for the exact JetStream cause (limits, permissions, etc.).","Raise the account's JetStream stream/storage limits if exhausted.","Check cluster health; replica creation fails if enough peers aren't available.","Ensure JetStream is enabled for the account and the server."],"exampleFix":null,"handlingStrategy":"retry","validationCode":"// Ensure account JS tier can host the sessions stream before CONNECT\nif (account.limits.jetstream.max_streams <= 0 || account.limits.jetstream.max_store <= 0) {\n  throw new Error('account JetStream limits too low for MQTT');\n}","typeGuard":null,"tryCatchPattern":"try {\n  await mqttConnect();\n} catch (e) {\n  if (/create sessions stream/.test(e.message)) {\n    raiseAccountJetStreamLimits();\n    return mqttConnect(); // retry after limits fixed\n  }\n  throw e;\n}","preventionTips":["Keep headroom in the account's max streams/storage quotas","Set mqtt.SessionReplicas no higher than cluster size","Upgrade servers uniformly before enabling replica streams","Alert on JetStream limit-approaching conditions"],"tags":["mqtt","jetstream","stream-creation"],"backgroundTag":"jetstream-stream-creation-failed","analyzedSha":"3a66a489d262bf89b71a71c955c94920394532f3","analyzedAt":"2026-09-02T04:41:54.247Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}