{"record":{"id":"1c99f489e6f37f1e","repo":"nats-io/nats-server","slug":"jetstream-cluster-requires-cluster-name-to-be-se","errorCode":null,"errorMessage":"jetstream cluster requires `cluster.name` to be set","messagePattern":"jetstream cluster requires `cluster\\.name` to be set","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"server/jetstream.go","lineNumber":2944,"sourceCode":"\t}\n\tif o.JetStreamDomain != _EMPTY_ {\n\t\tif subj := fmt.Sprintf(jsDomainAPI, o.JetStreamDomain); !IsValidSubject(subj) {\n\t\t\treturn fmt.Errorf(\"invalid domain name: derived %q is not a valid subject\", subj)\n\t\t}\n\n\t\tif !isValidName(o.JetStreamDomain) {\n\t\t\treturn fmt.Errorf(\"invalid domain name: may not contain ., * or >\")\n\t\t}\n\t}\n\t// If not clustered no checks needed past here.\n\tif !o.JetStream || o.Cluster.Port == 0 {\n\t\treturn nil\n\t}\n\tif o.ServerName == _EMPTY_ {\n\t\treturn fmt.Errorf(\"jetstream cluster requires `server_name` to be set\")\n\t}\n\tif o.Cluster.Name == _EMPTY_ {\n\t\treturn fmt.Errorf(\"jetstream cluster requires `cluster.name` to be set\")\n\t}\n\n\th := strings.ToLower(o.JetStreamExtHint)\n\tswitch h {\n\tcase jsWillExtend, jsNoExtend, _EMPTY_:\n\t\to.JetStreamExtHint = h\n\tdefault:\n\t\treturn fmt.Errorf(\"expected 'no_extend' for string value, got '%s'\", h)\n\t}\n\n\tif o.JetStreamMaxCatchup < 0 {\n\t\treturn fmt.Errorf(\"jetstream max catchup cannot be negative\")\n\t}\n\treturn nil\n}\n\n// We had a bug that set a default de dupe window on mirror, despite that being not a valid config\nfunc fixCfgMirrorWithDedupWindow(cfg *StreamConfig) {","sourceCodeStart":2926,"sourceCodeEnd":2962,"githubUrl":"https://github.com/nats-io/nats-server/blob/3a66a489d262bf89b71a71c955c94920394532f3/server/jetstream.go#L2926-L2962","documentation":"A JetStream clustered server must belong to a named cluster; the cluster name keys the raft group and meta layer. Validation rejects startup when jetstream is clustered but `cluster.name` is empty, even if cluster.port is set.","triggerScenarios":"Config with `jetstream {}` and `cluster { port: ... }` but no `cluster { name: ... }` value.","commonSituations":"Copy-pasting a clustering sample that only shows the port; removing the name line while keeping the rest of the cluster block.","solutions":["Add `cluster { name: \"<cluster-name>\" }` to the config; the name must match across all servers that should form one cluster.","Verify cluster.name is non-empty on every JetStream cluster member.","Restart the server."],"exampleFix":"// before\ncluster: { port: 6222 }\n// after\ncluster: { name: \"js-cluster\", port: 6222 }","handlingStrategy":"validation","validationCode":"if cfg.JetStream.Enabled && cfg.Cluster.Port != 0 && cfg.Cluster.Name == \"\" {\n    return errors.New(\"jetstream cluster requires cluster.name\")\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always pair cluster.port with cluster.name in config templates.","Keep cluster.name identical across all members of one cluster.","Validate full configs in CI before deploy."],"tags":["jetstream","clustering","configuration"],"backgroundTag":"missing-config-field","analyzedSha":"3a66a489d262bf89b71a71c955c94920394532f3","analyzedAt":"2026-09-02T04:41:54.247Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T15:18:49.778Z"}