{"record":{"id":"2244fe295c70a81f","repo":"nats-io/nats-server","slug":"failed-to-update-stream-config-w","errorCode":null,"errorMessage":"failed to update stream config: %w","messagePattern":"failed to update stream config: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"server/mqtt.go","lineNumber":1535,"sourceCode":"\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\n\t// Doing this check outside of above if/else due to possible race when\n\t// creating the stream.\n\twantedSubj := mqttRetainedMsgsStreamSubject + \">\"\n\tif len(si.Config.Subjects) != 1 || si.Config.Subjects[0] != wantedSubj {\n\t\t// Update only the Subjects at this stage, not MaxMsgsPer yet.\n\t\tsi.Config.Subjects = []string{wantedSubj}\n\t\tif si, err = jsa.updateStream(&si.Config); err != nil {\n\t\t\treturn nil, fmt.Errorf(\"failed to update stream config: %w\", err)\n\t\t}\n\t}\n\n\ttransferRMS := func() error {\n\t\tif !needToTransfer {\n\t\t\treturn nil\n\t\t}\n\n\t\tas.transferRetainedToPerKeySubjectStream(s)\n\n\t\t// We need another lookup to have up-to-date si.State values in order\n\t\t// to load all retained messages.\n\t\tsi, err = lookupStream(mqttRetainedMsgsStreamName, \"retained messages\")\n\t\tif err != nil {\n\t\t\treturn err\n\t\t}\n\t\tneedToTransfer = false\n\t\treturn nil","sourceCodeStart":1517,"sourceCodeEnd":1553,"githubUrl":"https://github.com/nats-io/nats-server/blob/3a66a489d262bf89b71a71c955c94920394532f3/server/mqtt.go#L1517-L1553","documentation":"The retained messages stream existed but its subjects did not match the expected single $MQTT.rmsgs subject, so the server attempted a stream update via updateStream; that update failed and the underlying JetStream error is wrapped here. It signals a stream config mismatch that could not be repaired automatically.","triggerScenarios":"An existing stream with the retained-messages name was created manually or by an older server version with different subjects; updateStream's JS API request fails (invalid config change, no permission, timeout, resources).","commonSituations":"Upgrading from an older NATS server whose MQTT retained stream used a different subject config; operator manually created/edited the stream; JetStream API errors like invalid stream configuration during update.","solutions":["Delete the existing retained messages stream ($MQTT.rmsgs related) while no MQTT clients are connected and let the server recreate it","Compare the stream's config with what the server expects and correct subjects manually via nats stream update","Check server logs for the wrapped update error (e.g. invalid config change, no responders) and address it","Run all server nodes on the same NATS Server version to avoid config schema mismatches"],"exampleFix":"// before\nnats stream info $MQTT.rmsgs   # subjects: [\"foo\"]\n// after\nnats stream rm $MQTT.rmsgs --force\n# restart MQTT clients; server recreates stream with subject $MQTT.rmsgs.>","handlingStrategy":"retry","validationCode":"// Verify the stream config matches what the server expects:\njs, _ := nc.JetStream()\nsi, err := js.StreamInfo(\"$MQTT.rmsgs\")\nif err == nil {\n    subjects := si.Config.Subjects\n    if len(subjects) != 1 || subjects[0] != \"$MQTT.rmsgs.>\" {\n        // mismatch: delete stream during maintenance so server recreates it\n    }\n}","typeGuard":null,"tryCatchPattern":"if err != nil && strings.Contains(err.Error(), \"failed to update stream config\") {\n    log.Printf(\"retained stream config mismatch: %v\", err)\n    // schedule maintenance deletion: nats stream rm $MQTT.rmsgs --force\n}","preventionTips":["Do not hand-edit internal $MQTT streams","Upgrade all servers together; never run mixed versions on one JS domain","If you must recreate the stream, do it with no MQTT clients connected"],"tags":["jetstream","mqtt","stream-update","config-mismatch"],"backgroundTag":"jetstream-stream-update-failed","analyzedSha":"3a66a489d262bf89b71a71c955c94920394532f3","analyzedAt":"2026-09-02T04:41:54.247Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}