hashicorp/nomad · error

alloc id must be set

Error message

alloc id must be set

What it means

ScheduleStateApplyRequest.Validate enforces that AllocID identifies the allocation whose task scheduling state is being changed. An empty AllocID fails immediately with 'alloc id must be set'. This is the first of three checks (alloc, task name, state enum).

Source

Thrown at nomad/structs/node.go:429

	QueryOptions // Client RPCs must use QueryOptions

	// NodeID is the node being targeted by this request (or the node receiving
	// this request if NodeID is empty).
	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
}

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Populate AllocID with the target allocation's UUID before calling Validate/Apply
2. Resolve the allocation ID via the allocations list API for the job/task first
3. Fail fast client-side when allocation lookup yields no ID instead of sending an empty request
4. Check upstream code paths for swallowed errors that leave AllocID unset

Example fix

// before
req := &structs.ScheduleStateApplyRequest{
  TaskName: "redis",
  ScheduleState: structs.TaskScheduleStateSchedPause,
}

// after
req := &structs.ScheduleStateApplyRequest{
  AllocID: allocID, // e.g. "e5f0b1c2-..."
  TaskName: "redis",
  ScheduleState: structs.TaskScheduleStateSchedPause,
}

if req.AllocID == "" {
	return errors.New("alloc id required before applying schedule state")
}

When it happens

Trigger: Submitting a ScheduleStateApplyRequest (task schedule state API) with r.AllocID == ""; caused by a caller that never populated the allocation ID after resolving the task.

Common situations: CLI/API automation pausing or resuming a task but passing an empty alloc ID because allocation lookup failed and the error was swallowed; templated requests with a missing placeholder.

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

• task name 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/32082719dc8068d0. Report an issue: GitHub.