nats-io/nats-server · error

gateway %q has no URL

Error message

gateway %q has no URL

What it means

A listed remote gateway must have at least one URL to connect to; without URLs the server has nowhere to dial for that cluster. The error names the gateway (as configured) so the incomplete entry can be found.

Source

Thrown at server/gateway.go:324

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 {
	sha := sha256.New()
	sha.Write([]byte(name))
	fullHash := []byte(fmt.Sprintf("%x", sha.Sum(nil)))

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Add at least one URL: gateway { name: "B", urls: ["nats://host:7222"] }
2. Check key spelling — the field is urls (array), not url
3. In code, append to RemoteGatewayOpts.URLs before calling server.New/ValidateOptions
4. If URLs come from discovery, log why the list resolved empty and add a fallback address

Example fix

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

for i, g := range opts.Gateway.Gateways {
    if g.Name != "" && len(g.URLs) == 0 { return fmt.Errorf("gateway %q missing urls", g.Name) }
}

err := server.ValidateOptions(opts)
if err != nil && strings.Contains(err.Error(), "has no URL") {
    // populate URLs for the named gateway before starting
}

When it happens

Trigger: A gateway { gateways: [ { name: "B" } ] } entry with no urls array, or RemoteGatewayOpts with empty URLs, during validateGatewayOptions/validateOptions at startup.

Common situations: Config omits the urls key, service discovery failed to populate URLs in generated configs, or a DNS/templating step produced an empty URL list; typos like 'url' instead of 'urls' also leave URLs empty.

Related errors

• gateway %q has no port specified (select -1 for random port)
• gateway in the list %d has no name
• 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/6e906b1012189aca. Report an issue: GitHub.