hashicorp/nomad · error

Consul Gateway Bind Address must be set

Error message

Consul Gateway Bind Address must be set

What it means

ConsulGatewayBindAddress.Validate found an empty Address on a gateway bind address stanza. The listener needs an explicit IP, or the field should be left to Nomad's autofill by providing a port of -1 with an address.

Source

Thrown at nomad/structs/services.go:2053

func (a *ConsulGatewayBindAddress) Copy() *ConsulGatewayBindAddress {
	if a == nil {
		return nil
	}

	return &ConsulGatewayBindAddress{
		Address: a.Address,
		Port:    a.Port,
	}
}

func (a *ConsulGatewayBindAddress) Validate() error {
	if a == nil {
		return nil
	}

	if a.Address == "" {
		return fmt.Errorf("Consul Gateway Bind Address must be set")
	}

	if a.Port <= 0 && a.Port != -1 { // port -1 => nomad autofill
		return fmt.Errorf("Consul Gateway Bind Address must set valid Port")
	}

	return nil
}

// ConsulGatewayProxy is used to tune parameters of the proxy instance acting as
// one of the forms of Connect gateways that Consul supports.
//
// https://www.consul.io/docs/connect/proxies/envoy#gateway-options
type ConsulGatewayProxy struct {
	ConnectTimeout                  *time.Duration
	EnvoyGatewayBindTaggedAddresses bool
	EnvoyGatewayBindAddresses       map[string]*ConsulGatewayBindAddress
	EnvoyGatewayNoDefaultBind       bool

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Set the bind address (e.g. 0.0.0.0) in the gateway listener stanza

When it happens

Trigger: Thrown at nomad/structs/services.go:2053 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of hashicorp/nomad@482b49bf1a (2026-09-04). Data as JSON: /api/errors/050f8d665e334ca8. Report an issue: GitHub.