hashicorp/nomad · error
timeout ( ) is lower than required minimum timeout
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.
Solutions
- Increase the check's timeout in the job spec to at least minCheckTimeout (use 2s or more, keeping timeout <= interval)
- Check for unit typos (1s vs 10s) in the HCL/JSON job file
- If you need faster failure detection, lower the interval as well, but keep timeout >= minCheckTimeout
- 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"
} Defensive patterns
Strategy: validation
Validate before calling
// 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)
} Prevention
- Always set timeout >= 1s and timeout <= interval in every check block
- Run `nomad job validate` in CI before job submission
- Keep shared check-configuration templates with sane defaults
- Watch for unit typos when converting milliseconds to duration strings
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 address_mode
- invalid address_mode
- invalid initial check state
- on_update must be , , or ; got
- allow_caps configured with capabilities not supported by…
AI-assisted analysis of hashicorp/nomad@482b49bf1a (2026-09-04).
Data as JSON: /api/errors/219d2ef7658f7011.
Report an issue: GitHub.
Appendix: 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)