nats-io/nats-server · error

cluster name cannot contain spaces

Error message

cluster name cannot contain spaces

What it means

Validation of a cluster name advertised on leaf node connections (INFO/CONNECT protocol): the name contains a space, which the protocol forbids. The connection is closed with ProtocolViolation after -ERR is sent. The advertised cluster name string is at fault.

Source

Thrown at server/errors.go:198

	// ErrBadMsgHeader signals the parser detected a bad message header
	ErrBadMsgHeader = errors.New("bad message header detected")

	// ErrMsgHeadersNotSupported signals the parser detected a message header
	// but they are not supported on this server.
	ErrMsgHeadersNotSupported = errors.New("message headers not supported")

	// ErrNoRespondersRequiresHeaders signals that a client needs to have headers
	// on if they want no responders behavior.
	ErrNoRespondersRequiresHeaders = errors.New("no responders requires headers support")

	// ErrClusterNameConfigConflict signals that the options for cluster name in cluster and gateway are in conflict.
	ErrClusterNameConfigConflict = errors.New("cluster name conflicts between cluster and gateway definitions")

	// ErrClusterNameRemoteConflict signals that a remote server has a different cluster name.
	ErrClusterNameRemoteConflict = errors.New("cluster name from remote server conflicts")

	// ErrClusterNameHasSpaces signals that the cluster name contains spaces, which is not allowed.
	ErrClusterNameHasSpaces = errors.New("cluster name cannot contain spaces")

	// ErrClusterNameReserved signals that the cluster name is reserved for internal protocol use.
	ErrClusterNameReserved = errors.New("cluster name is reserved")

	// ErrMalformedSubject is returned when a subscription is made with a subject that does not conform to subject rules.
	ErrMalformedSubject = errors.New("malformed subject")

	// ErrSubscribePermissionViolation is returned when processing of a subscription fails due to permissions.
	ErrSubscribePermissionViolation = errors.New("subscribe permission violation")

	// ErrNoTransforms signals no subject transforms are available to map this subject.
	ErrNoTransforms = errors.New("no matching transforms available")

	// ErrCertNotPinned is returned when pinned certs are set and the certificate is not in it
	ErrCertNotPinned = errors.New("certificate not pinned")

	// ErrDuplicateServerName is returned when processing a server remote connection and
	// the server reports that this server name is already used in the cluster.

View on GitHub (pinned to 3a66a489d2)

Solutions

  1. Rename the cluster to a token without spaces
  2. Check for stray whitespace or missing quotes in the cluster name option
  3. Fix the remote server's cluster name that is being advertised
Defensive patterns

Strategy: validation

When it happens

Trigger: Thrown at server/errors.go:198 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/9ecc1f767828268c. Report an issue: GitHub.