hashicorp/nomad · error

Missing HealthCheck

Error message

Missing HealthCheck

What it means

MigrateStrategy.Validate requires a HealthCheck value when MaxParallel > 0, because migrations need a health criterion (checks or states) to decide which allocations are healthy. An empty HealthCheck with active migration concurrency yields this error. It prevents deploying migrations that can never evaluate allocation health.

Source

Thrown at nomad/structs/structs.go:6848

		HealthCheck:     MigrateStrategyHealthChecks,
		MinHealthyTime:  10 * time.Second,
		HealthyDeadline: 5 * time.Minute,
	}
}

func (m *MigrateStrategy) Validate() error {
	var mErr multierror.Error

	if m.MaxParallel < 0 {
		_ = multierror.Append(&mErr, fmt.Errorf("MaxParallel must be >= 0 but found %d", m.MaxParallel))
	}

	switch m.HealthCheck {
	case MigrateStrategyHealthChecks, MigrateStrategyHealthStates:
		// ok
	case "":
		if m.MaxParallel > 0 {
			_ = multierror.Append(&mErr, fmt.Errorf("Missing HealthCheck"))
		}
	default:
		_ = multierror.Append(&mErr, fmt.Errorf("Invalid HealthCheck: %q", m.HealthCheck))
	}

	if m.MinHealthyTime < 0 {
		_ = multierror.Append(&mErr, fmt.Errorf("MinHealthyTime is %s and must be >= 0", m.MinHealthyTime))
	}

	if m.HealthyDeadline < 0 {
		_ = multierror.Append(&mErr, fmt.Errorf("HealthyDeadline is %s and must be >= 0", m.HealthyDeadline))
	}

	if m.MinHealthyTime > m.HealthyDeadline {
		_ = multierror.Append(&mErr, fmt.Errorf("MinHealthyTime must be less than HealthyDeadline"))
	}

	return mErr.ErrorOrNil()

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Add health_checks = "checks" (uses Nomad service checks) to the update block.
2. Or use health_checks = "states" to rely on allocation/task states only.
3. Set max_parallel = 0 if no migration behavior is desired, making HealthCheck optional.
4. Validate the job spec before submission.

Example fix

// before
update {
  max_parallel = 1
}
// after
update {
  max_parallel  = 1
  health_checks = "checks"
}

func validHealthCheck(m *structs.MigrateStrategy) error {
	if m.MaxParallel > 0 && m.HealthCheck == "" {
		return errors.New("health_checks is required when max_parallel > 0")
	}
	return nil
}

func hasHealthCheckWhenMigrating(m *structs.MigrateStrategy) bool {
	return m.MaxParallel <= 0 || m.HealthCheck != ""
}

if err := strategy.Validate(); err != nil {
	if err.Error() == "Missing HealthCheck" {
		// set health_checks to "checks" or "states" before resubmit
	}
}

When it happens

Trigger: Submitting a job with update block: max_parallel set (>0) but health_checks omitted/empty string.

Common situations: Minimal update blocks that only specify max_parallel; HCL files migrated from older job specs; generated configs that omit health_checks assuming a default.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• MaxParallel must be >= 0 but found %d
• Invalid HealthCheck: %q
• MinHealthyTime is %s and must be >= 0
• HealthyDeadline is %s and must be >= 0
• MinHealthyTime must be less than HealthyDeadline

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