{"record":{"id":"e2d727aed399f4e2","repo":"nats-io/nats-server","slug":"jetstream-cluster-requires-cluster-name","errorCode":null,"errorMessage":"JetStream cluster requires cluster name","messagePattern":"JetStream cluster requires cluster name","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"server/jetstream_cluster.go","lineNumber":1270,"sourceCode":"\tif !s.isRunning() {\n\t\treturn nil\n\t}\n\tjs := s.getJetStream()\n\tif js == nil {\n\t\treturn NewJSNotEnabledForAccountError()\n\t}\n\t// Already set.\n\tif js.cluster != nil {\n\t\treturn nil\n\t}\n\n\ts.Noticef(\"Starting JetStream cluster\")\n\t// We need to determine if we have a stable cluster name and expected number of servers.\n\ts.Debugf(\"JetStream cluster checking for stable cluster name and peers\")\n\n\thasLeafNodeSystemShare := s.canExtendOtherDomain()\n\tif s.isClusterNameDynamic() && !hasLeafNodeSystemShare {\n\t\treturn errors.New(\"JetStream cluster requires cluster name\")\n\t}\n\tif s.configuredRoutes() == 0 && !hasLeafNodeSystemShare {\n\t\treturn errors.New(\"JetStream cluster requires configured routes or solicited leafnode for the system account\")\n\t}\n\n\treturn js.setupMetaGroup()\n}\n\n// isClustered returns if we are clustered.\n// Lock should not be held.\nfunc (js *jetStream) isClustered() bool {\n\t// This is only ever set, no need for lock here.\n\treturn js.cluster != nil\n}\n\n// isClusteredNoLock returns if we are clustered, but unlike isClustered() does\n// not use the jetstream's lock, instead, uses an atomic operation.\n// There are situations where some code wants to know if we are clustered but","sourceCodeStart":1252,"sourceCodeEnd":1288,"githubUrl":"https://github.com/nats-io/nats-server/blob/3a66a489d262bf89b71a71c955c94920394532f3/server/jetstream_cluster.go#L1252-L1288","documentation":"enableJetStreamClustering returns this when JetStream clustering is being enabled but the server's cluster name is dynamic (not statically configured) and the server cannot extend another domain via leaf nodes. JetStream clustering requires a stable cluster name so raft meta groups and asset placement are consistent across restarts; a dynamically generated name would break peer identity.","triggerScenarios":"Config has `jetstream { ... }` plus clustering enabled (store_dir etc. with js clustering via leafnode/system share absent) while `cluster { name }` is unset, causing isClusterNameDynamic() to be true; s.canExtendOtherDomain() is false because no solicited leafnode connection shares the system account.","commonSituations":"Operator enables JetStream clustering but forgets to set cluster.name in the config; config templating drops the cluster block; leafnode-based extension expected but the leaf connection is not configured with the system account.","solutions":["Set a stable `cluster { name: \"<name>\" }` block in the server config.","If you intended leafnode extension, configure a solicited leafnode connection sharing the system account so hasLeafNodeSystemShare is true.","Re-check the rendered config (nats-server --config ... --signal reload or start logs) to ensure the cluster name is present at runtime.","Restart the server after fixing the config; clustering setup runs when JetStream clustering is enabled."],"exampleFix":"// before\njetstream {\n  store_dir: \"/data/js\"\n}\n// after\njetstream {\n  store_dir: \"/data/js\"\n}\ncluster {\n  name: \"nats-cluster-a\"\n  listen: \"0.0.0.0:6222\"\n  routes: [\n    \"nats://nats-1:6222\",\n    \"nats://nats-2:6222\"\n  ]\n}","handlingStrategy":"validation","validationCode":"// Validate config before startup: cluster name must be set for JS clustering\nif cfg.Cluster == nil || cfg.Cluster.Name == \"\" {\n    return errors.New(\"jetstream clustering requires cluster.name\")\n}\n","typeGuard":null,"tryCatchPattern":"// Go: fail fast at config load time\nif err := server.Start(); err != nil && strings.Contains(err.Error(), \"requires cluster name\") {\n    return fmt.Errorf(\"config error: set cluster.name in server config: %w\", err)\n}","preventionTips":["Always set cluster.name when enabling JetStream clustering","Validate rendered configs in CI before deployment","Do not rely on dynamic cluster names for clustered JetStream","Document the leafnode/system-account alternative if intentionally using it"],"tags":["jetstream","nats","configuration","clustering"],"backgroundTag":"missing-config-value","analyzedSha":"3a66a489d262bf89b71a71c955c94920394532f3","analyzedAt":"2026-09-02T04:41:54.247Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}