{"record":{"id":"666d3814e97dc364","repo":"nats-io/nats-server","slug":"lookup-s-stream-for-account-q-v","errorCode":null,"errorMessage":"lookup %s stream for account %q: %v","messagePattern":"lookup (.+?) stream for account %q: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"server/mqtt.go","lineNumber":1397,"sourceCode":"\t// Start the go routine that will send JS API requests.\n\ts.startGoRoutine(func() {\n\t\tdefer s.grWG.Done()\n\t\tas.sendJSAPIrequests(s, c, accName, closeCh)\n\t})\n\n\t// Start the go routine that will clean up cached retained messages that expired.\n\ts.startGoRoutine(func() {\n\t\tdefer s.grWG.Done()\n\t\tas.cleanupRetainedMessageCache(s, closeCh)\n\t})\n\n\tlookupStream := func(stream, txt string) (*StreamInfo, error) {\n\t\tsi, err := jsa.lookupStream(stream)\n\t\tif err != nil {\n\t\t\tif IsNatsErr(err, JSStreamNotFoundErr) {\n\t\t\t\treturn nil, nil\n\t\t\t}\n\t\t\treturn nil, fmt.Errorf(\"lookup %s stream for account %q: %v\", txt, accName, err)\n\t\t}\n\t\tif opts.MQTT.StreamReplicas == 0 {\n\t\t\treturn si, nil\n\t\t}\n\t\tsr := 1\n\t\tif si.Cluster != nil {\n\t\t\tsr += len(si.Cluster.Replicas)\n\t\t}\n\t\tif replicas != sr {\n\t\t\ts.Warnf(\"MQTT %s stream replicas mismatch: current is %v but configuration is %v for '%s > %s'\",\n\t\t\t\ttxt, sr, replicas, accName, stream)\n\t\t}\n\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 {","sourceCodeStart":1379,"sourceCodeEnd":1415,"githubUrl":"https://github.com/nats-io/nats-server/blob/3a66a489d262bf89b71a71c955c94920394532f3/server/mqtt.go#L1379-L1415","documentation":"During MQTT JetStream stream setup for an account, mqtt.jsStreamConfig looks up existing streams (messages, sessions, QoS2, retained, etc.) via jsa.lookupStream. If the lookup fails with anything other than JSStreamNotFoundErr, the error is wrapped with the role of the stream (txt) and account name so operators know which stream lookup failed. Stream-not-found is treated as normal (stream will be created), all other lookup errors are fatal here.","triggerScenarios":"jsa.lookupStream(stream) returns an error that is not JSStreamNotFoundErr — e.g. JetStream not enabled for the account, account JS resources exhausted, API/permission errors, raft/cluster issues — inside the lookupStream closure of mqttJSStreamConfig.","commonSituations":"MQTT enabled but JetStream not enabled on the account/server; missing JS permissions for the account; JS storage/account limits reached; cluster instability; misconfigured JS domain.","solutions":["Read the wrapped inner error after 'lookup ... stream for account' to get the underlying JetStream cause.","Enable JetStream on the server and grant the account JS permissions and limits.","Check JetStream cluster health (server logs, jsz) if errors reference raft/metadata.","Verify the account's JS tier/resource limits aren't exhausted."],"exampleFix":null,"handlingStrategy":"retry","validationCode":"// Pre-check server/account readiness before connecting MQTT clients\n// nats account info: JetStream enabled and resources available\nif (!account.jetstream || !account.jetstream.enabled) throw new Error('JetStream required for MQTT');","typeGuard":null,"tryCatchPattern":"try {\n  await mqttConnect();\n} catch (e) {\n  if (/lookup .* stream for account/.test(e.message)) {\n    // JetStream lookup failed; wait for JS health then retry\n    await waitForJetStreamHealthy();\n    return mqttConnect();\n  }\n  throw e;\n}","preventionTips":["Enable JetStream on the server and the account before enabling MQTT","Grant the account JS user permissions and adequate limits","Monitor JetStream cluster health (jsz) in production","Align JS domain configuration across servers"],"tags":["mqtt","jetstream","stream-lookup","configuration"],"backgroundTag":"jetstream-stream-lookup-failed","analyzedSha":"3a66a489d262bf89b71a71c955c94920394532f3","analyzedAt":"2026-09-02T04:41:54.247Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T15:18:49.778Z"}