hashicorp/nomad · error

timeout (%v) is lower than required minimum timeout %v

Error message

timeout (%v) is lower than required minimum timeout %v

What it means

This error is raised by ServiceCheck.validateCommon in Nomad's structs package when a service check's Timeout is non-zero but smaller than minCheckTimeout. Nomad enforces a floor on check timeouts (reported against minCheckInterval) to prevent checks whose timeout is too short to ever pass. Job submission fails validation before the job is registered.

Source

Thrown at nomad/structs/services.go:295

		}
	case ServiceCheckScript:
		if sc.Command == "" {
			return fmt.Errorf("script type must have a valid script path")
		}
	}

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

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Increase the check's timeout in the job spec to at least minCheckTimeout (use 2s or more, keeping timeout <= interval)
2. Check for unit typos (1s vs 10s) in the HCL/JSON job file
3. If you need faster failure detection, lower the interval as well, but keep timeout >= minCheckTimeout
4. Run nomad job validate <file> locally before submitting to catch this before the API call

Example fix

// before
check {
  type     = "http"
  path     = "/health"
  interval = "10s"
  timeout  = "1s"
}
// after
check {
  type     = "http"
  path     = "/health"
  interval = "10s"
  timeout  = "2s"
}

// Go: validate check timeout before submitting the job
func validTimeout(d time.Duration) bool {
	const minCheckTimeout = 1 * time.Second // Nomad's minimum
	return d >= minCheckTimeout
}
if !validTimeout(check.Timeout) {
	return fmt.Errorf("check timeout %v must be >= 1s", check.Timeout)
}

When it happens

Trigger: Submitting a job whose service block defines a check with an explicit timeout lower than minCheckTimeout, e.g. check { type = "http" path = "/health" interval = "10s" timeout = "1s" } passed to jobs.register or nomad job run.

Common situations: Copying check configs tuned for very fast local probes from Consul/other tools into Nomad; typos like timeout = "1s" intended as "10s"; assuming Nomad allows sub-second or very tight timeouts like Consul does.

Understand the failure class

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

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