hashicorp/nomad · error

task name must be set

Error message

task name must be set

What it means

ScheduleStateApplyRequest.Validate requires TaskName to identify which task inside the allocation the schedule state (run/force_run/sched_pause/force_pause) applies to. An empty TaskName fails with 'task name must be set'.

Source

Thrown at nomad/structs/node.go:433

	NodeID string

	// AllocID is the allocation being targeted by this request.
	AllocID string

	// TaskName is the name of the task being targeted by this request.
	TaskName string

	// State is the state to apply to the task being targeted by this request.
	ScheduleState TaskScheduleState
}

func (r *ScheduleStateApplyRequest) Validate() error {
	if r.AllocID == "" {
		return errors.New("alloc id must be set")
	}

	if r.TaskName == "" {
		return errors.New("task name must be set")
	}

	switch r.ScheduleState {
	case TaskScheduleStateRun:
	case TaskScheduleStateForceRun:
	case TaskScheduleStateSchedPause:
	case TaskScheduleStateForcePause:
	default:
		return errors.New("not a valid task schedule state")
	}

	return nil
}

// ScheduleStateReadRequest is used to read the current pause state of a specific
// task running on a client.
type ScheduleStateReadRequest struct {
	QueryOptions // Client RPCs must use QueryOptions

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Set TaskName to the exact task name from the job specification
2. Look up the task name from the allocation's TaskStates map or job spec rather than hardcoding
3. Check for task renames between job versions that invalidate hardcoded names
4. Validate client-side (non-empty TaskName) before hitting the API

Example fix

// before
req := &structs.ScheduleStateApplyRequest{
  AllocID: allocID,
  ScheduleState: structs.TaskScheduleStateForcePause,
}

// after
req := &structs.ScheduleStateApplyRequest{
  AllocID: allocID,
  TaskName: "redis",
  ScheduleState: structs.TaskScheduleStateForcePause,
}

if req.TaskName == "" {
	return errors.New("task name required before applying schedule state")
}

When it happens

Trigger: Submitting a ScheduleStateApplyRequest with r.TaskName == "" after AllocID passed validation; commonly when callers target 'the only task' implicitly.

Common situations: Automation assuming a single-task allocation and omitting task name; HCL/JSON job files where task names differ from what tooling sends; renamed tasks after a template change.

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

• alloc id must be set
• missing name
• not a valid task schedule state
• missing secret ID
• namespace cannot contain template delimiters or parenthesis

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