hashicorp/nomad · error

KillTimeout must be a positive value

Error message

KillTimeout must be a positive value

What it means

Task validation guard in Task.Validate: fires when a task's kill_timeout is zero or negative. Nomad requires a positive duration so the driver knows how long to wait after SIGTERM before force-killing the task. Non-fatal validation error returned to the job submitter; fix by setting kill_timeout to a positive duration (e.g. "5s").

Source

Thrown at nomad/structs/structs.go:8250

	}

	// Tasks cannot be named "alloc" as this conflicts with and breaks task
	// filesystem isolation features.
	if t.Name == "alloc" {
		mErr.Errors = append(mErr.Errors, errors.New("Task cannot be named \"alloc\""))
	}
	if strings.ContainsAny(t.Name, `/\`) {
		// We enforce this so that when creating the directory on disk it will
		// not have any slashes.
		mErr.Errors = append(mErr.Errors, errors.New("Task name cannot include slashes"))
	} else if strings.Contains(t.Name, "\000") {
		mErr.Errors = append(mErr.Errors, errors.New("Task name cannot include null characters"))
	}
	if t.Driver == "" {
		mErr.Errors = append(mErr.Errors, errors.New("Missing task driver"))
	}
	if t.KillTimeout < 0 {
		mErr.Errors = append(mErr.Errors, errors.New("KillTimeout must be a positive value"))
	} else {
		// Validate the group's update strategy does not conflict with the
		// task's kill_timeout for service jobs.
		//
		// progress_deadline = 0 has a special meaning so it should not be
		// validated against the task's kill_timeout.
		conflictsWithProgressDeadline := jobType == JobTypeService &&
			tg.Update != nil &&
			tg.Update.ProgressDeadline > 0 &&
			t.KillTimeout > tg.Update.ProgressDeadline
		if conflictsWithProgressDeadline {
			mErr.Errors = append(mErr.Errors, fmt.Errorf("KillTimout (%s) longer than the group's ProgressDeadline (%s)",
				t.KillTimeout, tg.Update.ProgressDeadline))
		}
	}
	if t.ShutdownDelay < 0 {
		mErr.Errors = append(mErr.Errors, errors.New("ShutdownDelay must be a positive value"))
	}

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Set kill_timeout to a positive duration, e.g. kill_timeout = "30s".
2. Clamp negative durations to 0 (default) in generation code.
3. Validate before submit.

Example fix

// before
task "app" {
  kill_timeout = "-30s"
}
// after
task "app" {
  kill_timeout = "30s"
}

if t.KillTimeout < 0 {
  return fmt.Errorf("task %q kill_timeout must be >= 0", t.Name)
}

func isNonNegativeDuration(d time.Duration) bool {
  return d >= 0
}

When it happens

Trigger: A task sets `kill_timeout = "-30s"` or a programmatically built task has a negative time.Duration in KillTimeout.

Common situations: Sign mistakes in HCL durations; arithmetic producing negative durations in generated configs.

Understand the failure class

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

Related errors

• Missing task name
• Task cannot be named "alloc"
• Task name cannot include slashes
• Task name cannot include null characters
• Missing task driver

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