What causes "gateway has no name" in nats-io/nats-server?

Add gateway { name: " " } to the server config next to the port.

gateway has no name

Error message

gateway has no name

What it means

The 'gateway has no name' error comes from validateGatewayOptions in server/gateway.go: it is returned when gateway options enable a gateway (non-zero Port) but leave Gateway.Name empty. Gateways need a unique cluster name to identify the gateway cluster during connections, so starting the server with a port but no name is a configuration error.

Source

Thrown at server/gateway.go:311

	}
	clone := &RemoteGatewayOpts{
		Name: r.Name,
		URLs: deepCopyURLs(r.URLs),
	}
	if r.TLSConfig != nil {
		clone.TLSConfig = r.TLSConfig.Clone()
		clone.TLSTimeout = r.TLSTimeout
	}
	return clone
}

// Ensure that gateway is properly configured.
func validateGatewayOptions(o *Options) error {
	if o.Gateway.Name == _EMPTY_ && o.Gateway.Port == 0 {
		return nil
	}
	if o.Gateway.Name == _EMPTY_ {
		return errors.New("gateway has no name")
	}
	if strings.Contains(o.Gateway.Name, " ") {
		return ErrGatewayNameHasSpaces
	}
	if o.Gateway.Port == 0 {
		return fmt.Errorf("gateway %q has no port specified (select -1 for random port)", o.Gateway.Name)
	}
	for i, g := range o.Gateway.Gateways {
		if g.Name == _EMPTY_ {
			return fmt.Errorf("gateway in the list %d has no name", i)
		}
		if len(g.URLs) == 0 {
			return fmt.Errorf("gateway %q has no URL", g.Name)
		}
	}
	if err := validatePinnedCerts(o.Gateway.TLSPinnedCerts); err != nil {
		return fmt.Errorf("gateway %q: %v", o.Gateway.Name, err)
	}

View on GitHub (pinned to 3a66a489d2)

Solutions

Add gateway { name: "<cluster-name>" } to the server config next to the port.
Or set o.Gateway.Name in code before nats-server validates options.
If gateways are not intended, remove the gateway port setting so both name and port are empty (gateways disabled).

Example fix

// before
gateway {
  port: 7222
}
// after
gateway {
  name: "A"
  port: 7222
}

Defensive patterns

Strategy: validation

Validate before calling

if o.Gateway.Port != 0 && o.Gateway.Name == "" {
    return errors.New("gateway port set but gateway.name missing")
}

Try / catch

if err := validateGatewayOptions(opts); err != nil {
    if strings.Contains(err.Error(), "gateway has no name") {
        log.Fatal("add gateway.name to config")
    }
}

Prevention

Always pair gateway.port with gateway.name in config templates.
Validate config with nats-server --test before startup.
Ensure template variables for gateway.name are non-empty.

When it happens

Trigger: Config sets gateway { port: N } (or -P gateway flag / Gateway.Port != 0) but omits gateway.name; validateOptions calls validateGatewayOptions which rejects empty names at startup. Note: name AND port both empty is allowed (gateways disabled).

Common situations: Adding a gateway port to a config that previously had no gateway section and forgetting the name field; templated configs where the name variable is empty; copy of a config stripped of the name.

Related errors

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