nats-io/nats-server · error

gateway name cannot contain spaces

Error message

gateway name cannot contain spaces

What it means

ErrGatewayNameHasSpaces signals that the configured gateway name contains a space character, which NATS forbids because gateway names are used as protocol identifiers between clusters. It is returned by validateGatewayOptions (server/gateway.go:314) at startup and also surfaced as a configErr when parsing config files (server/opts.go:2290).

Source

Thrown at server/errors.go:165

	ErrServiceImportAuthorization = errors.New("service import not authorized")

	// ErrImportFormsCycle is returned when an import would form a cycle.
	ErrImportFormsCycle = errors.New("import forms a cycle")

	// ErrCycleSearchDepth is returned when we have exceeded our maximum search depth..
	ErrCycleSearchDepth = errors.New("search cycle depth exhausted")

	// ErrClientOrRouteConnectedToGatewayPort represents an error condition when
	// a client or route attempted to connect to the Gateway port.
	ErrClientOrRouteConnectedToGatewayPort = errors.New("attempted to connect to gateway port")

	// ErrWrongGateway represents an error condition when a server receives a connect
	// 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

View on GitHub (pinned to 3a66a489d2)

Solutions

  1. Remove the space from the gateway name, e.g. use "us-east" or "us_east".
  2. Quote/normalize environment variables used for gateway names before substitution.
  3. Re-run the server; ProcessConfigFile will report the offending token via configErr if it remains.

Example fix

// before
gateway { name: "us east", port: 7222 }
// after
gateway { name: "us-east", port: 7222 }
Defensive patterns

Strategy: validation

Validate before calling

// Validate the gateway name before rendering config:
if strings.ContainsAny(gwName, " ") || gwName == "" {
    return fmt.Errorf("gateway name %q must not contain spaces", gwName)
}

Try / catch

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

Prevention

When it happens

Trigger: Setting `gateway { name: "my gateway" }` in the server config; passing a gateway name with a space via flag/programmatic Options; config-file variable substitution producing a name with a space.

Common situations: Names copied from environment names like "us east" into config; interpolating `${REGION}` that contains spaces; hand-edited configs on multi-cluster deployments.

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/216a2b3ec6e12edf. Report an issue: GitHub.