nats-io/nats-server · error

jetstream cluster requires `server_name` to be set

Error message

jetstream cluster requires `server_name` to be set

What it means

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.

Source

Thrown at server/jetstream.go:2941

				return fmt.Errorf("default_js_domain contains account %q with invalid domain name %q", a, d)
			}
		}
	}
	if o.JetStreamDomain != _EMPTY_ {
		if subj := fmt.Sprintf(jsDomainAPI, o.JetStreamDomain); !IsValidSubject(subj) {
			return fmt.Errorf("invalid domain name: derived %q is not a valid subject", subj)
		}

		if !isValidName(o.JetStreamDomain) {
			return fmt.Errorf("invalid domain name: may not contain ., * or >")
		}
	}
	// If not clustered no checks needed past here.
	if !o.JetStream || o.Cluster.Port == 0 {
		return nil
	}
	if o.ServerName == _EMPTY_ {
		return fmt.Errorf("jetstream cluster requires `server_name` to be set")
	}
	if o.Cluster.Name == _EMPTY_ {
		return fmt.Errorf("jetstream cluster requires `cluster.name` to be set")
	}

	h := strings.ToLower(o.JetStreamExtHint)
	switch h {
	case jsWillExtend, jsNoExtend, _EMPTY_:
		o.JetStreamExtHint = h
	default:
		return fmt.Errorf("expected 'no_extend' for string value, got '%s'", h)
	}

	if o.JetStreamMaxCatchup < 0 {
		return fmt.Errorf("jetstream max catchup cannot be negative")
	}
	return nil
}

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Set a unique `server_name` for every server in the cluster, e.g. `server_name: "nats-1"`.
2. Ensure the value differs across cluster members, since JetStream replica placement depends on it.
3. Restart the server.

Example fix

// before
jetstream: {}
cluster: { port: 6222 }
// after
server_name: "nats-1"
jetstream: {}
cluster: { port: 6222 }

if cfg.JetStream.Enabled && cfg.Cluster.Port != 0 && cfg.ServerName == "" {
    return errors.New("jetstream cluster requires server_name")
}

When it happens

Trigger: Config with `jetstream {}` enabled plus a `cluster { port: ... }` block while `server_name` is empty or unset.

Common situations: Adding a cluster block to an existing standalone JetStream server config that never defined server_name; template-generated configs omitting server_name.

Related errors

• JetStream cluster requires cluster name
• JetStream cluster requires configured routes or solicited le
• jetstream cluster requires `cluster.name` to be set
• system account not setup
• duplicate server name

AI-assisted analysis of nats-io/nats-server@3a66a489d2 (2026-09-02). Data as JSON: /api/errors/65e7ad54b3879130. Report an issue: GitHub.