grace period must be greater than or equal to 0 but found %d

Error message

grace period must be greater than or equal to 0 but found %d

What it means

CheckRestart.Validate: the grace period (time between task restart and health checking) is negative. Grace durations must be zero or a positive duration string.

Source

Thrown at nomad/structs/structs.go:7830

	if c.IgnoreWarnings != o.IgnoreWarnings {
		return false
	}

	return true
}

func (c *CheckRestart) Validate() error {
	if c == nil {
		return nil
	}

	var mErr multierror.Error
	if c.Limit < 0 {
		mErr.Errors = append(mErr.Errors, fmt.Errorf("limit must be greater than or equal to 0 but found %d", c.Limit))
	}

	if c.Grace < 0 {
		mErr.Errors = append(mErr.Errors, fmt.Errorf("grace period must be greater than or equal to 0 but found %d", c.Grace))
	}

	return mErr.ErrorOrNil()
}

const (
	// DefaultKillTimeout is the default timeout between signaling a task it
	// will be killed and killing it.
	DefaultKillTimeout = 5 * time.Second
)

// LogConfig provides configuration for log rotation
type LogConfig struct {
	MaxFiles      int
	MaxFileSizeMB int
	Disabled      bool
}

View on GitHub (pinned to 482b49bf1a)

Solutions

Set `grace` to a positive duration string (e.g. "90s")
Remove `grace` to use the service default
Validate duration signs in your config pipeline before rendering

Example fix

// before
check_restart { grace = "-30s" }
// after
check_restart { grace = "30s" }

Defensive patterns

Strategy: validation

Validate before calling

if cr != nil && cr.Grace < 0 {
  return fmt.Errorf("check_restart.grace must be >= 0, got %d", cr.Grace)
}

Type guard

func validGrace(cr *api.CheckRestart) bool {
  return cr == nil || cr.Grace >= 0
}

Prevention

Use time.ParseDuration on inputs and reject negatives
Never compute grace from subtraction that can go negative
Validate rendered HCL with `nomad job validate` before submit

When it happens

Trigger: Submitting a job with `check_restart { grace = "-5s" }` or a CheckRestart struct with Grace < 0.

Common situations: Parsing durations from config where sign is lost; copy-paste typos with a stray minus; templated durations computed as (now - later).

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

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