nats-io/nats-server · error

cluster: %v

Error message

cluster: %v

What it means

Generic cluster-validation wrapper in validateCluster: a subordinate check (cluster permissions subjects, compression validation, or pinned TLS certs) failed and its error is wrapped with the 'cluster:' prefix to attribute it to the cluster configuration block. The underlying %v error names the real problem; inspect it rather than this prefix.

Source

Thrown at server/server.go:1122

}

func validateCluster(o *Options) error {
	if o.Cluster.Name != _EMPTY_ && strings.Contains(o.Cluster.Name, " ") {
		return ErrClusterNameHasSpaces
	}
	if p := o.Cluster.Permissions; p != nil {
		perms := &Permissions{Publish: p.Import, Subscribe: p.Export}
		if err := checkClusterPermissionSubjects(perms); err != nil {
			return err
		}
	}
	if o.Cluster.Compression.Mode != _EMPTY_ {
		if err := validateAndNormalizeCompressionOption(&o.Cluster.Compression, CompressionS2Fast); err != nil {
			return err
		}
	}
	if err := validatePinnedCerts(o.Cluster.TLSPinnedCerts); err != nil {
		return fmt.Errorf("cluster: %v", err)
	}
	// Check that cluster name if defined matches any gateway name.
	// Note that we have already verified that the gateway name does not have spaces.
	if o.Gateway.Name != _EMPTY_ && o.Gateway.Name != o.Cluster.Name {
		if o.Cluster.Name != _EMPTY_ {
			return ErrClusterNameConfigConflict
		}
		// Set this here so we do not consider it dynamic.
		o.Cluster.Name = o.Gateway.Name
	}
	clusterName := o.Cluster.Name
	if clusterName == _EMPTY_ && len(o.LeafNode.Remotes) > 0 && o.Cluster.Port == 0 {
		clusterName = o.ServerName
	}
	if clusterName == leafNoOriginCluster {
		return ErrClusterNameReserved
	}
	if l := len(o.Cluster.PinnedAccounts); l > 0 {

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Read the wrapped error text to identify the failing cluster sub-check
2. Fix the offending cluster config section (permissions, compression, tls.pinned_certs)
3. Re-run nats-server -t (or --config with dry check) to re-validate the config

When it happens

Trigger: Thrown at server/server.go:1122 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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