hashicorp/nomad · error

Service address_mode must be %q if address is set

Error message

Service address_mode must be %q if address is set

What it means

In Service.Validate, an explicit service Address was set while AddressMode was one of host/driver/alloc/alloc_ipv6. A static address is only meaningful in auto mode, where Nomad substitutes the interpolated address into the service registration.

Source

Thrown at nomad/structs/services.go:778

// Validate checks if the Service definition is valid
func (s *Service) Validate() error {
	var mErr multierror.Error

	// Ensure the service name is valid per the below RFCs but make an exception
	// for our interpolation syntax by first stripping any environment variables from the name

	serviceNameStripped := args.ReplaceEnvWithPlaceHolder(s.Name, "ENV-VAR")

	if err := s.ValidateName(serviceNameStripped); err != nil {
		// Log actual service name, not the stripped version.
		mErr.Errors = append(mErr.Errors, fmt.Errorf("%v: %q", err, s.Name))
	}

	switch s.AddressMode {
	case "", AddressModeAuto:
	case AddressModeHost, AddressModeDriver, AddressModeAlloc, AddressModeAllocIPv6:
		if s.Address != "" {
			mErr.Errors = append(mErr.Errors, fmt.Errorf("Service address_mode must be %q if address is set", AddressModeAuto))
		}
	default:
		mErr.Errors = append(mErr.Errors, fmt.Errorf("Service address_mode must be %q, %q, or %q; not %q", AddressModeAuto, AddressModeHost, AddressModeDriver, s.AddressMode))
	}

	switch s.OnUpdate {
	case "", OnUpdateIgnore, OnUpdateRequireHealthy, OnUpdateIgnoreWarn:
		// OK
	default:
		mErr.Errors = append(mErr.Errors, fmt.Errorf("Service on_update must be %q, %q, or %q; not %q", OnUpdateRequireHealthy, OnUpdateIgnoreWarn, OnUpdateIgnore, s.OnUpdate))
	}

	// Up until this point, all service validation has been independent of the
	// provider. From this point on, we have different validation paths. We can
	// also catch an incorrect provider parameter.
	switch s.Provider {
	case ServiceProviderConsul:
		s.validateConsulService(&mErr)

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Remove the address field and rely on address_mode
2. Set address_mode to "auto" (or omit it) when address is specified

Example fix

// before
address_mode = "host"
address = "10.0.0.5"
// after
address_mode = "auto"
address = "10.0.0.5"

if s.Address != "" && s.AddressMode != "" && s.AddressMode != structs.AddressModeAuto {
    return fmt.Errorf("address must use address_mode=auto")
}

When it happens

Trigger: Setting both Service.Address (non-empty) and Service.AddressMode to host, driver, alloc, or alloc_ipv6, then validating.

Common situations: Migrating configs from host-address style to address_mode without removing the address field; generators emitting both fields.

Related errors

• address_mode = driver may only be set for Consul service che
• Service address_mode must be %q, %q, or %q; not %q
• service %q cannot use address_mode="driver", only services d
• Check %q invalid: cannot use address_mode="driver", only che
• missing secret ID

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