hashicorp/nomad · error

invalid address_mode %q - %s only valid for services

Error message

invalid address_mode %q - %s only valid for services

What it means

Raised by ServiceCheck.validateCommon when a service check sets address_mode = "auto". The auto address mode is only valid on the service itself, not on individual checks; Nomad rejects it at check-validation time with a message clarifying that auto is service-only.

Source

Thrown at nomad/structs/services.go:313

		return fmt.Errorf("timeout (%v) is lower than required minimum timeout %v", sc.Timeout, minCheckInterval)
	}

	// 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

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Remove address_mode from the check block so it inherits the service's address mode
2. Use "host" or "driver" explicitly on the check instead of "auto"
3. If you need auto resolution, set address_mode = "auto" on the parent service only
4. Run nomad job validate before submitting

Example fix

// before
service {
  name = "web"
  check {
    address_mode = "auto"
    type         = "http"
    path         = "/health"
  }
}
// after
service {
  name         = "web"
  address_mode = "auto"
  check {
    type = "http"
    path = "/health"
  }
}

// Go: reject address_mode="auto" on checks before submission
if check.AddressMode == structs.AddressModeAuto {
	return fmt.Errorf("address_mode auto is only valid on services, not checks")
}

When it happens

Trigger: A check block inside a service specifies address_mode = "auto" (e.g. check { address_mode = "auto" ... }); job submitted via nomad job run or jobs API.

Common situations: Assuming the service's address_mode value can be inherited or repeated on checks; copy-pasting the service-level address_mode into the check block; bridge-networking configs where auto seems natural.

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
• 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/8f28715d9b3e8440. Report an issue: GitHub.