hashicorp/nomad · error

Consul Gateway Bind Address must set valid Port

Error message

Consul Gateway Bind Address must set valid Port

What it means

ConsulGatewayBindAddress.Validate found a Port that is zero/negative and not the -1 sentinel. Port -1 tells Nomad to autofill (e.g. for dynamic ingress ports); any other non-positive value is rejected.

Source

Thrown at nomad/structs/services.go:2057

	}

	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
	EnvoyDNSDiscoveryType           string
	Config                          map[string]any
}

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Set port to a positive value (1-65535)
2. Set port to -1 to let Nomad autofill the port

When it happens

Trigger: Thrown at nomad/structs/services.go:2057 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/02d5cd67f793470d. Report an issue: GitHub.