hashicorp/nomad · error

on_update must be %q, %q, or %q; got %q

Error message

on_update must be %q, %q, or %q; got %q

What it means

Raised by ServiceCheck.validateCommon when a check's on_update field is not one of the allowed values: require_healthy, ignore_warning, ignore, or empty (which defaults to require_healthy). on_update controls how the updater treats check results during deployments, so Nomad validates it strictly at registration time.

Source

Thrown at nomad/structs/services.go:323

		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)
		}
		// CheckRestart IgnoreWarnings must be true if a check has defined OnUpdate
		// ignore_warnings
		if !sc.CheckRestart.IgnoreWarnings && sc.OnUpdate == OnUpdateIgnoreWarn {
			return fmt.Errorf("on_update value %q not supported with check_restart ignore_warnings value %q", sc.OnUpdate, strconv.FormatBool(sc.CheckRestart.IgnoreWarnings))
		}
	}

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Set on_update to exactly "require_healthy", "ignore_warning", or "ignore" (lowercase, underscore)
2. Omit on_update to accept the require_healthy default
3. Check for pluralization/spacing typos (ignore_warnings, ignore-warning are invalid)
4. Run nomad job validate before submission

Example fix

// before
check {
  type      = "http"
  path      = "/health"
  on_update = "ignore_warnings"
}
// after
check {
  type      = "http"
  path      = "/health"
  on_update = "ignore_warning"
}

// Go: whitelist on_update before submission
var validOnUpdate = map[string]bool{
	"": true,
	"require_healthy": true, "ignore_warning": true, "ignore": true,
}
if !validOnUpdate[check.OnUpdate] {
	return fmt.Errorf("on_update %q invalid; use require_healthy|ignore_warning|ignore", check.OnUpdate)
}

When it happens

Trigger: Submitting a job with check { on_update = "ignore_warnings" } or any string other than require_healthy/ignore_warning/ignore, via nomad job run or the jobs API.

Common situations: Singular/plural confusion (ignore_warning vs ignore_warnings); guessing value names instead of checking docs; copying on_update conventions from health-check tooling with different vocabularies.

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

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

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