{"record":{"id":"926920b0460a4d14","repo":"nats-io/nats-server","slug":"create-retained-messages-stream-for-account-q-v","errorCode":null,"errorMessage":"create retained messages stream for account %q: %v","messagePattern":"create retained messages stream for account %q: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"server/mqtt.go","lineNumber":1509,"sourceCode":"\tswitch {\n\tcase err != nil:\n\t\treturn nil, err\n\n\tcase si == nil:\n\t\t// Create the stream for retained messages.\n\t\tcfg := &StreamConfig{\n\t\t\tName:       mqttRetainedMsgsStreamName,\n\t\t\tSubjects:   []string{mqttRetainedMsgsStreamSubject + \">\"},\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\t// We will need \"si\" outside of this block.\n\t\tsi, _, err = jsa.createStream(cfg)\n\t\tif err != nil {\n\t\t\tif isErrorOtherThan(err, JSStreamNameExistErr) {\n\t\t\t\treturn nil, fmt.Errorf(\"create retained messages stream for account %q: %v\", accName, err)\n\t\t\t}\n\t\t\t// Suppose we had a race and the stream was actually created by another\n\t\t\t// node, we really need \"si\" after that, so lookup the stream again here.\n\t\t\tsi, err = lookupStream(mqttRetainedMsgsStreamName, \"retained messages\")\n\t\t\tif err != nil {\n\t\t\t\treturn nil, err\n\t\t\t}\n\t\t}\n\t\tneedToTransfer = false\n\n\tdefault:\n\t\tneedToTransfer = si.Config.MaxMsgsPer != 1\n\t}\n\t// Guard before dereferencing si.Config below.\n\tif si == nil {\n\t\treturn nil, fmt.Errorf(\"could not look up or create the retained messages stream for account %q\", accName)\n\t}\n","sourceCodeStart":1491,"sourceCodeEnd":1527,"githubUrl":"https://github.com/nats-io/nats-server/blob/3a66a489d262bf89b71a71c955c94920394532f3/server/mqtt.go#L1491-L1527","documentation":"This error wraps a failure to create the internal JetStream stream that backs MQTT retained messages ($MQTT.rmsgs stream) for an account. The NATS server creates this stream on demand when an MQTT client session is set up; if createStream fails with anything other than 'stream already exists', the original error is wrapped with the account name for context. It indicates a JetStream-level problem preventing stream creation.","triggerScenarios":"JetStream disabled or not ready on the server; an existing stream with the same name but incompatible config; JetStream API request failing (e.g. storage resources unavailable, insufficient resources); internal JSAPI request timeout when creating the retained-messages stream during MQTT session/account setup.","commonSituations":"Running an MQTT client against a server where JetStream is not enabled; disk full or storage limits hit so the stream cannot be created; cluster where the JS API request times out; misconfigured stream limits in server config.","solutions":["Enable JetStream (remove --js disabled / set jetstream {} in config) or verify the account has JetStream enabled","Check server logs for the wrapped underlying error (e.g. no resources, low storage) and free disk/memory or raise resource limits","Check for a pre-existing conflicting stream named for retained messages with an incompatible config and delete/recreate it","Restart the server / retry connection once JetStream is healthy"],"exampleFix":"// before (server config)\n// jetstream disabled\n// after\njetstream {\n  store_dir: \"/data/nats\"\n  max_memory_store: 1GB\n  max_file_store: 10GB\n}","handlingStrategy":"validation","validationCode":"// Before connecting MQTT clients, verify JetStream is enabled and healthy:\nnc, _ := nats.Connect(url)\njs, _ := nc.JetStream()\n_, err := js.AccountInfo()\nif err != nil {\n    // JetStream unavailable: enable it in server config before MQTT use\n    log.Fatalf(\"JetStream not available: %v\", err)\n}","typeGuard":null,"tryCatchPattern":"if err != nil {\n    if strings.Contains(err.Error(), \"create retained messages stream\") {\n        // check JetStream status, then retry with backoff\n        retryWithBackoff(func() error { return reconnectMQTT() })\n    }\n}","preventionTips":["Always enable JetStream when using the MQTT subsystem","Monitor disk/memory stores so stream creation never fails on resources","Use consistent server versions across the cluster","Pre-create or audit the retained messages stream before scaling MQTT clients"],"tags":["jetstream","mqtt","stream-creation","nats-server"],"backgroundTag":"jetstream-stream-create-failed","analyzedSha":"3a66a489d262bf89b71a71c955c94920394532f3","analyzedAt":"2026-09-02T04:41:54.247Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T15:18:49.778Z"}