hashicorp/nomad · error

invalid address_mode %q

Error message

invalid address_mode %q

What it means

Raised by ServiceCheck.validateCommon when a check's address_mode is a string that is not one of the recognized modes: "" (unset), host, driver, alloc, or alloc_ipv6. Unlike the "auto" case, this means the value did not match any known address mode at all, typically a typo or a mode from a different/newer Nomad version.

Source

Thrown at nomad/structs/services.go:315

	// validate the initial status
	switch sc.InitialStatus {
	case "":
	case api.HealthPassing:
	case api.HealthWarning:
	case api.HealthCritical:
	default:
		return fmt.Errorf(`invalid initial check state (%s), must be one of %q, %q, %q or empty`, sc.InitialStatus, api.HealthPassing, api.HealthWarning, api.HealthCritical)
	}

	// validate address_mode
	switch sc.AddressMode {
	case "", AddressModeHost, AddressModeDriver, AddressModeAlloc, AddressModeAllocIPv6:
		// Ok
	case AddressModeAuto:
		return fmt.Errorf("invalid address_mode %q - %s only valid for services", sc.AddressMode, AddressModeAuto)
	default:
		return fmt.Errorf("invalid address_mode %q", sc.AddressMode)
	}

	// validate on_update
	switch sc.OnUpdate {
	case "", OnUpdateIgnore, OnUpdateRequireHealthy, OnUpdateIgnoreWarn:
		// OK
	default:
		return fmt.Errorf("on_update must be %q, %q, or %q; got %q", OnUpdateRequireHealthy, OnUpdateIgnoreWarn, OnUpdateIgnore, sc.OnUpdate)
	}

	// validate check_restart and on_update do not conflict
	if sc.CheckRestart != nil {
		// CheckRestart and OnUpdate Ignore are incompatible If OnUpdate treats
		// an error has healthy, and the deployment succeeds followed by check
		// restart restarting failing checks, the deployment is left in an odd
		// state
		if sc.OnUpdate == OnUpdateIgnore {
			return fmt.Errorf("on_update value %q is not compatible with check_restart", sc.OnUpdate)

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Correct the address_mode value to one of: host, driver, alloc, alloc_ipv6, or remove it to use the default
2. Check the Nomad version's supported address modes against the job spec
3. Check for typos in the value
4. Run nomad job validate to confirm

Example fix

// before
check {
  address_mode = "container"
  type         = "http"
  path         = "/health"
}
// after
check {
  address_mode = "driver"
  type         = "http"
  path         = "/health"
}

// Go: check address_mode against the known set
var validAddrModes = map[string]bool{
	"": true, "host": true, "driver": true, "alloc": true, "alloc_ipv6": true,
}
if !validAddrModes[check.AddressMode] {
	return fmt.Errorf("address_mode %q not recognized", check.AddressMode)
}

When it happens

Trigger: Submitting a job with check { address_mode = "container" } or any unrecognized string, via nomad job run or the jobs API.

Common situations: Typos like "hosts" or "drier"; using address modes from other platforms (e.g. "container" from Docker wording); running a job spec written for a newer Nomad that supports a mode this binary does not know.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• invalid address_mode %q - %s only valid for services
• timeout (%v) is lower than required minimum timeout %v
• invalid initial check state (%s), must be one of %q, %q, %q
• on_update must be %q, %q, or %q; got %q
• failed to parse config:

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