{"record":{"id":"a6d76451425aa324","repo":"nats-io/nats-server","slug":"leaf-nodes-and-gateways-both-being-defined-requi","errorCode":null,"errorMessage":"leaf nodes and gateways (both being defined) require a system account to also be configured","messagePattern":"leaf nodes and gateways \\(both being defined\\) require a system account to also be configured","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"server/leafnode.go","lineNumber":349,"sourceCode":"\n\t// If MinVersion is defined, check that it is valid.\n\tif mv := o.LeafNode.MinVersion; mv != _EMPTY_ {\n\t\tif err := checkLeafMinVersionConfig(mv); err != nil {\n\t\t\treturn err\n\t\t}\n\t}\n\n\t// The checks below will be done only when detecting that we are configured\n\t// with gateways. So if an option validation needs to be done regardless,\n\t// it MUST be done before this point!\n\n\tif o.Gateway.Name == _EMPTY_ && o.Gateway.Port == 0 {\n\t\treturn nil\n\t}\n\t// If we are here we have both leaf nodes and gateways defined, make sure there\n\t// is a system account defined.\n\tif o.SystemAccount == _EMPTY_ {\n\t\treturn fmt.Errorf(\"leaf nodes and gateways (both being defined) require a system account to also be configured\")\n\t}\n\tif err := validatePinnedCerts(o.LeafNode.TLSPinnedCerts); err != nil {\n\t\treturn fmt.Errorf(\"leafnode: %v\", err)\n\t}\n\treturn nil\n}\n\nfunc checkLeafMinVersionConfig(mv string) error {\n\tif ok, err := versionAtLeastCheckError(mv, 2, 8, 0); !ok || err != nil {\n\t\tif err != nil {\n\t\t\treturn fmt.Errorf(\"invalid leafnode's minimum version: %v\", err)\n\t\t} else {\n\t\t\treturn fmt.Errorf(\"the minimum version should be at least 2.8.0\")\n\t\t}\n\t}\n\treturn nil\n}\n","sourceCodeStart":331,"sourceCodeEnd":367,"githubUrl":"https://github.com/nats-io/nats-server/blob/3a66a489d262bf89b71a71c955c94920394532f3/server/leafnode.go#L331-L367","documentation":"When both leaf nodes and a gateway are configured, the server requires a system account so that cluster/supercluster control messages have an account to run under. validateLeafNode throws this during Options validation when Options defines leaf node connections and a gateway (name or port) but Options.SystemAccount is empty. Without it, routing of system-level interest between leaf nodes and gateways cannot work correctly.","triggerScenarios":"Calling server.NewServer(opts) / opts.Validate() (via validateOptions -> validateLeafNode) where o.LeafNode is configured AND (o.Gateway.Name != \"\" or o.Gateway.Port != 0) AND o.SystemAccount == \"\".","commonSituations":"Operators add a gateway block to an existing config that only had leaf nodes (or vice versa) and forget the accounts.system_account setting; templates copied from simple leaf-node examples then extended with clustering.","solutions":["Add a system account to the config, e.g. accounts { SYS { ... } } and system_account = \"SYS-internal-nkey\"","Generate an account NKEY with nsc and set it as system_account in Options","If gateways are not actually needed, remove the gateway name/port configuration"],"exampleFix":"// before\nleafnodes { ... }\ngateway { name: \"A\", port: 7222 }\n// after\naccounts { SYS { users: [ { nkey: \"AB...\" } ] } }\nsystem_account: \"AB...\"\nleafnodes { ... }\ngateway { name: \"A\", port: 7222 }","handlingStrategy":"validation","validationCode":"if (opts.LeafNode != nil && hasLeafRemotes(opts)) &&\n   (opts.Gateway.Name != \"\" || opts.Gateway.Port != 0) &&\n   opts.SystemAccount == \"\" {\n  return errors.New(\"leafnodes + gateway require a system account\")\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always define a system account in clustered/leaf topologies","Run `nats-server -t` in CI on every config change","Use a shared config template that includes accounts.SYS and system_account"],"tags":["leafnode","gateway","system-account","config-validation"],"backgroundTag":"missing-system-account","analyzedSha":"3a66a489d262bf89b71a71c955c94920394532f3","analyzedAt":"2026-09-02T04:41:54.247Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}