{"record":{"id":"f04ebea28a41adf1","repo":"nats-io/nats-server","slug":"remote-s-s","errorCode":null,"errorMessage":"remote %s: %s","messagePattern":"remote (.+?): (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"server/reload.go","lineNumber":999,"sourceCode":"\t\t\tif rlo == nil {\n\t\t\t\t// Not found, will be removed in leafNodeOption.Apply().\n\t\t\t\tremoved = true\n\t\t\t\tlrc.RUnlock()\n\t\t\t\tcontinue\n\t\t\t}\n\t\t\t// Now we need to make sure that there are no changes that we don't\n\t\t\t// support for a RemoteLeafOpts.\n\t\t\terr := checkConfigsEqual(lrc.RemoteLeafOpts, rlo, []string{\n\t\t\t\t\"Compression\",\n\t\t\t\t\"Disabled\",\n\t\t\t\t\"TLS\",\n\t\t\t\t\"TLSHandshakeFirst\",\n\t\t\t\t\"TLSConfig\",\n\t\t\t})\n\t\t\tif err != nil {\n\t\t\t\tlrc.RUnlock()\n\t\t\t\ts.mu.RUnlock()\n\t\t\t\treturn nil, fmt.Errorf(remoteErrFormat, rlo.safeName(), err)\n\t\t\t}\n\t\t\tdisabledChanged := lrc.Disabled != rlo.Disabled\n\t\t\t// If this remote was disabled and is now enabled, we need to make sure\n\t\t\t// that there is no connect in progress. If that is the case, either\n\t\t\t// try again (if it is the first failure) or return an error.\n\t\t\tif disabledChanged && lrc.Disabled && lrc.connInProgress {\n\t\t\t\tlrc.RUnlock()\n\t\t\t\ts.mu.RUnlock()\n\t\t\t\tif failed < maxAttempts-1 {\n\t\t\t\t\tcontinue forLoop\n\t\t\t\t}\n\t\t\t\treturn nil, fmt.Errorf(remoteErrFormat, rlo.safeName(),\n\t\t\t\t\t\"cannot be enabled at the moment, try again\")\n\t\t\t}\n\t\t\t// Since we will use the new `rlo.TLSConfig` later on, consider all\n\t\t\t// existing remote configs as \"changed\" and store them in the\n\t\t\t// `nlo.changed` map.\n\t\t\tif nlo.changed == nil {","sourceCodeStart":981,"sourceCodeEnd":1017,"githubUrl":"https://github.com/nats-io/nats-server/blob/3a66a489d262bf89b71a71c955c94920394532f3/server/reload.go#L981-L1017","documentation":"While diffing leaf node remotes during reload, checkConfigsEqual on a leaf remote (leafnodes.remotes[i]) returned an unsupported field change (TLSHandshakeFirst, TLSConfig, etc. are in the ignore list but the rest failed). The error is wrapped as remote <name>: <cause>.","triggerScenarios":"Editing a field of an existing leafnodes.remotes[] entry that cannot be hot-reloaded (e.g. credentials, urls, TLS details) and calling Reload() or sending SIGHUP.","commonSituations":"Rotating leaf remote credentials or URLs via reload; adding/removing accounts in a remote entry; changing TLS material of a running remote connection.","solutions":["Revert the unsupported remote field in the config, or restart the server to apply it.","Restrict reload edits to supported remote fields (check NATS reload docs for the allow-list).","Split changes: reload supported fields now; schedule a restart for the remote connection changes."],"exampleFix":"// before (reload)\nleafnodes { remotes: [ { url: \"nats://other:4222\", credentials: \"new.creds\" } ] }\n// after\nleafnodes { remotes: [ { url: \"nats://other:4222\", credentials: \"old.creds\" } ] } // restart to swap creds","handlingStrategy":"validation","validationCode":"// pre-validate that only hot-reloadable leaf remote fields changed\nunsupported := []string{\"credentials\", \"tls\", \"urls\"}\nfor _, f := range unsupported {\n    if remoteChanged(oldRemote, newRemote, f) {\n        return fmt.Errorf(\"field %q of leaf remote requires restart\", f)\n    }\n}","typeGuard":null,"tryCatchPattern":"if err := srv.Reload(); err != nil {\n    if strings.HasPrefix(err.Error(), \"remote \") {\n        log.Printf(\"leaf remote reload rejected, restart needed: %v\", err)\n    }\n}","preventionTips":["Consult the NATS reload documentation allow-list before editing leaf remotes live.","Rotate leaf remote credentials via restarts in maintenance windows.","Version-control configs and diff before reload."],"tags":["reload","leafnodes","remotes"],"backgroundTag":"config-reload-unsupported-change","analyzedSha":"3a66a489d262bf89b71a71c955c94920394532f3","analyzedAt":"2026-09-02T04:41:54.247Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}