invalid initial check state (%s), must be one of %q, %q, %q

Error message

invalid initial check state (%s), must be one of %q, %q, %q or empty

What it means

Raised by ServiceCheck.validateCommon when a check's initial_status field is not one of the allowed Consul health states: passing, warning, critical, or the empty string. Nomad validates the value at job-registration time because it is forwarded to Consul as the check's starting state. Any other string causes the job to be rejected.

Source

Thrown at nomad/structs/services.go:305

	} else if sc.Interval < minCheckInterval {
		return fmt.Errorf("interval (%v) cannot be lower than %v", sc.Interval, minCheckInterval)
	}

	// validate timeout
	if sc.Timeout == 0 {
		return fmt.Errorf("missing required value timeout. Timeout cannot be less than %v", minCheckInterval)
	} else if sc.Timeout < minCheckTimeout {
		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)

View on GitHub (pinned to 482b49bf1a)

Solutions

Set initial_status to exactly "passing", "warning", or "critical" (lowercase)
Omit initial_status entirely (empty defaults to Consul's behavior)
Check for capitalization/whitespace in the HCL value
Run nomad job validate to confirm before submission

Example fix

// before
check {
  type           = "http"
  path           = "/health"
  initial_status = "healthy"
}
// after
check {
  type           = "http"
  path           = "/health"
  initial_status = "passing"
}

Defensive patterns

Strategy: validation

Validate before calling

// Go: whitelist valid initial_status values
var validInitialStatus = map[string]bool{
	nomadApi.HealthPassing: true, "": true,
	nomadApi.HealthWarning: true, nomadApi.HealthCritical: true,
}
if !validInitialStatus[check.InitialStatus] {
	return fmt.Errorf("initial_status %q invalid; use passing|warning|critical or empty", check.InitialStatus)
}

Prevention

Use only lowercase "passing", "warning", "critical" for initial_status
Prefer omitting initial_status unless you specifically need a pre-state
Lint job files against Nomad's schema in CI
Run `nomad job validate` before every submit

When it happens

Trigger: Submitting a job with a check block containing initial_status = "healthy", "ok", "PASSING", or any value other than "passing"/"warning"/"critical"/empty, via nomad job run or the jobs API.

Common situations: Using synonyms like "healthy" or "ok" instead of Consul's exact state names; capitalization mistakes (the comparison is case-sensitive); copying values from other orchestrators with different state 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

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