{"record":{"id":"0f80096390ecc56d","repo":"nats-io/nats-server","slug":"create-messages-stream-for-account-q-v","errorCode":null,"errorMessage":"create messages stream for account %q: %v","messagePattern":"create messages stream for account %q: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"server/mqtt.go","lineNumber":1444,"sourceCode":"\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}\n\n\tif si, err := lookupStream(mqttQoS2IncomingMsgsStreamName, \"QoS2 incoming messages\"); err != nil {\n\t\treturn nil, err\n\t} else if si == nil {\n\t\t// Create the stream for the incoming QoS2 messages that have not been\n\t\t// PUBREL-ed by the sender. Subject is\n\t\t// \"$MQTT.qos2.<session>.<PI>\", the .PI is to achieve exactly\n\t\t// once for each PI.\n\t\tcfg := &StreamConfig{\n\t\t\tName:          mqttQoS2IncomingMsgsStreamName,\n\t\t\tSubjects:      []string{mqttQoS2IncomingMsgsStreamSubjectPrefix + \">\"},\n\t\t\tStorage:       FileStorage,\n\t\t\tRetention:     LimitsPolicy,\n\t\t\tDiscard:       DiscardNew,\n\t\t\tMaxMsgsPer:    1,\n\t\t\tDiscardNewPer: true,","sourceCodeStart":1426,"sourceCodeEnd":1462,"githubUrl":"https://github.com/nats-io/nats-server/blob/3a66a489d262bf89b71a71c955c94920394532f3/server/mqtt.go#L1426-L1462","documentation":"The MQTT messages stream (subject prefix mqttStreamSubjectPrefix + '>' under FileStorage with InterestPolicy) is created on first MQTT use per account. If createStream returns an error other than JSStreamNameExistErr, this wrapped error identifies which stream and account failed. Name-exists is treated as success because another server already created the stream.","triggerScenarios":"jsa.createStream(cfg) for the '<account>-mqtt-messages' stream fails with anything except JSStreamNameExistErr — e.g. account storage quota exceeded, JS API errors, or invalid replica counts vs cluster size.","commonSituations":"Disk/storage limits reached for the account; JetStream not enabled; replicas > available cluster nodes; temporary JS unavailability during CONNECT.","solutions":["Inspect the wrapped inner error for the precise JetStream failure reason.","Increase the account's JS storage/stream limits or free storage.","Ensure the cluster has enough nodes for the configured StreamReplicas.","Verify JetStream is enabled and healthy on the server."],"exampleFix":null,"handlingStrategy":"retry","validationCode":"// Check the account has free JS storage/streams before first MQTT use\nif (account.jsUsage.store >= account.limits.jetstream.max_store) {\n  throw new Error('account JetStream storage exhausted; MQTT messages stream will fail to create');\n}","typeGuard":null,"tryCatchPattern":"try {\n  await mqttConnect();\n} catch (e) {\n  if (/create messages stream/.test(e.message)) {\n    freeOrRaiseStorageQuota();\n    return mqttConnect();\n  }\n  throw e;\n}","preventionTips":["Monitor account JS storage usage against limits","Keep disk headroom on FileStorage-backed streams","Ensure cluster has enough peers for the replica count","Confirm JetStream is enabled before routing MQTT clients"],"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"}