nats-io/nats-server · error

gateway %q has no port specified (select -1 for random port)

Error message

gateway %q has no port specified (select -1 for random port)

What it means

Option validation for clustered gateways (validateGatewayOptions) requires an explicit Gateway.Port. Port 0 is treated as unset; NATS uses -1 to mean 'pick a random port', so 0 is rejected with guidance to use -1 instead.

Source

Thrown at server/gateway.go:317

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

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

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Set gateway { port: -1 } in the config to request a random port
2. Or set an explicit port, e.g. gateway { port: 7222 }
3. In code, set opts.Gateway.Port = -1 (or a real port) instead of leaving the zero value
4. Check for config templating/rendering that dropped the port value

Example fix

// before (config)
gateway { name: "A" }
// after
gateway { name: "A", port: -1 }  # or port: 7222

// validate gateway options before server.New
if opts.Gateway != nil && opts.Gateway.Name != "" && opts.Gateway.Port == 0 {
    opts.Gateway.Port = -1 // or an explicit port
}

o, err := server.ProcessConfigFile(cfgPath)
if err != nil {
    if strings.Contains(err.Error(), "has no port specified") {
        o.Gateway.Port = -1
    }
}
// or: nats-server -t config.conf in CI to catch it pre-deploy

When it happens

Trigger: Starting a server with a gateway block that has a name but no port: gateway { name: "A" } with no port field, or programmatically Options.Gateway.Port == 0, passed to validateOptions at startup.

Common situations: Config file omits the gateway port, a template left the port blank, or code copying options reset Port to its zero value; users often expect 0 to mean random as it does for client ports.

Related errors

• gateway in the list %d has no name
• 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/a01ae6bc723a1ee9. Report an issue: GitHub.