nats-io/nats-server · error

gateway in the list %d has no name

Error message

gateway in the list %d has no name

What it means

Every remote gateway listed under o.Gateway.Gateways must have a name; an empty name cannot be used to compute the 6-character gateway routing hash or to address the remote cluster. The error reports the index in the list so the offender can be located.

Source

Thrown at server/gateway.go:321

}

// 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)
	}
	return nil
}

// Computes a hash of 6 characters for the name.
// This will be used for routing of replies.
func getGWHash(name string) []byte {
	return []byte(getHashSize(name, gwHashLen))
}

func getOldHash(name string) []byte {

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Add gateway { name: "B" } to the offending gateways entry (index given in the message)
2. In code, set RemoteGatewayOpts.Name to the remote cluster's exact name
3. Validate the rendered config file (nats-server -t) before deploy
4. Ensure config generators emit non-empty names for every gateways entry

Example fix

// before
gateways: [ { urls: ["nats://b:7222"] } ]
// after
gateways: [ { name: "B", urls: ["nats://b:7222"] } ]

for i, g := range opts.Gateway.Gateways {
    if g.Name == "" { return fmt.Errorf("gateway entry %d missing name", i) }
}

err := server.ValidateOptions(opts)
if err != nil && strings.Contains(err.Error(), "has no name") {
    // parse index from message and fix that gateways entry
}

When it happens

Trigger: A gateway { gateways: [ { urls: [...] } ] } entry missing the name field, or programmatically a RemoteGatewayOpts with Name == "" inside Options.Gateway.Gateways during validateOptions at startup.

Common situations: Hand-edited config dropped the name key, generated config left a name placeholder empty, or constructing []RemoteGatewayOpts in Go code without setting Name.

Related errors

• gateway %q has no port specified (select -1 for random port)
• gateway %q has no URL
• ack wait must be a positive value
• JS API timeout must be a positive value
• publish deny: %w

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