{"record":{"id":"65e7ad54b3879130","repo":"nats-io/nats-server","slug":"jetstream-cluster-requires-server-name-to-be-set","errorCode":null,"errorMessage":"jetstream cluster requires `server_name` to be set","messagePattern":"jetstream cluster requires `server_name` to be set","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"server/jetstream.go","lineNumber":2941,"sourceCode":"\t\t\t\treturn fmt.Errorf(\"default_js_domain contains account %q with invalid domain name %q\", a, d)\n\t\t\t}\n\t\t}\n\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}","sourceCodeStart":2923,"sourceCodeEnd":2959,"githubUrl":"https://github.com/nats-io/nats-server/blob/3a66a489d262bf89b71a71c955c94920394532f3/server/jetstream.go#L2923-L2959","documentation":"When JetStream clustering is enabled (jetstream enabled and cluster.port set), each server must have a unique `server_name` because JetStream places stream replicas by server name. The server refuses to start with clustered JetStream and no server_name.","triggerScenarios":"Config with `jetstream {}` enabled plus a `cluster { port: ... }` block while `server_name` is empty or unset.","commonSituations":"Adding a cluster block to an existing standalone JetStream server config that never defined server_name; template-generated configs omitting server_name.","solutions":["Set a unique `server_name` for every server in the cluster, e.g. `server_name: \"nats-1\"`.","Ensure the value differs across cluster members, since JetStream replica placement depends on it.","Restart the server."],"exampleFix":"// before\njetstream: {}\ncluster: { port: 6222 }\n// after\nserver_name: \"nats-1\"\njetstream: {}\ncluster: { port: 6222 }","handlingStrategy":"validation","validationCode":"if cfg.JetStream.Enabled && cfg.Cluster.Port != 0 && cfg.ServerName == \"\" {\n    return errors.New(\"jetstream cluster requires server_name\")\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always set a unique server_name when clustering is enabled.","Generate server_name from hostname in config templates.","Check cluster member names are unique before rollout."],"tags":["jetstream","clustering","configuration","server-name"],"backgroundTag":"missing-config-field","analyzedSha":"3a66a489d262bf89b71a71c955c94920394532f3","analyzedAt":"2026-09-02T04:41:54.247Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}