nats-io/nats-server · error

jetstream cluster requires `cluster.name` to be set

Error message

jetstream cluster requires `cluster.name` to be set

What it means

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.

Source

Thrown at server/jetstream.go:2944

	}
	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
}

// We had a bug that set a default de dupe window on mirror, despite that being not a valid config
func fixCfgMirrorWithDedupWindow(cfg *StreamConfig) {

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Add `cluster { name: "<cluster-name>" }` to the config; the name must match across all servers that should form one cluster.
2. Verify cluster.name is non-empty on every JetStream cluster member.
3. Restart the server.

Example fix

// before
cluster: { port: 6222 }
// after
cluster: { name: "js-cluster", port: 6222 }

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

When it happens

Trigger: Config with `jetstream {}` and `cluster { port: ... }` but no `cluster { name: ... }` value.

Common situations: Copy-pasting a clustering sample that only shows the port; removing the name line while keeping the rest of the cluster block.

Related errors

• JetStream cluster requires cluster name
• JetStream cluster requires configured routes or solicited le
• jetstream cluster requires `server_name` to be set
• system account not setup
• stream assignment or group missing

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