nats-io/nats-server · error

server name cannot contain spaces

Error message

server name cannot contain spaces

What it means

ErrServerNameHasSpaces signals that the configured server name contains a space, which NATS disallows because the server name appears in protocol messages and route/gateway identification. It is produced by config validation in server/opts.go:1159 as a configErr attached to the offending token, and tests assert ProcessConfigFile returns it (server_test.go:2400).

Source

Thrown at server/errors.go:178

	// request from a remote Gateway with a destination name that does not match the server's
	// Gateway's name.
	ErrWrongGateway = errors.New("wrong gateway")

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

	// ErrNoSysAccount is returned when an attempt to publish or subscribe is made
	// when there is no internal system account defined.
	ErrNoSysAccount = errors.New("system account not setup")

	// ErrRevocation is returned when a credential has been revoked.
	ErrRevocation = errors.New("credentials have been revoked")

	// ErrServerNotRunning is used to signal an error that a server is not running.
	ErrServerNotRunning = errors.New("server is not running")

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

	// 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")

View on GitHub (pinned to 3a66a489d2)

Solutions

  1. Replace spaces with dashes or underscores, e.g. `server_name: "prod-server-01"`.
  2. If the name comes from a template/env var, sanitize it (tr -s ' ' '-') before rendering the config.
  3. Rely on the hostname (default) or `hostport`-style names if unique display names are not required.

Example fix

// before
server_name: "prod server 01"
// after
server_name: "prod-server-01"
Defensive patterns

Strategy: validation

Validate before calling

// Validate server_name before rendering/starting:
if strings.ContainsAny(serverName, " ") {
    return fmt.Errorf("server_name %q must not contain spaces", serverName)
}

Try / catch

if err := RunServer(opts); err != nil {
    if errors.Is(err, ErrServerNameHasSpaces) {
        // sanitize: strings.ReplaceAll(name, " ", "-") and restart
    }
}

Prevention

When it happens

Trigger: Setting `server_name: "my server"` in the config file; `--name "prod server"` on the command line; hostname-derived names containing spaces (rare, but via templating/substitution).

Common situations: Templated configs where a display name with spaces is substituted into server_name; users naming servers after human-readable cluster labels.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

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