{"record":{"id":"32082719dc8068d0","repo":"hashicorp/nomad","slug":"alloc-id-must-be-set","errorCode":null,"errorMessage":"alloc id must be set","messagePattern":"alloc id must be set","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"nomad/structs/node.go","lineNumber":429,"sourceCode":"\tQueryOptions // Client RPCs must use QueryOptions\n\n\t// NodeID is the node being targeted by this request (or the node receiving\n\t// this request if NodeID is empty).\n\tNodeID string\n\n\t// AllocID is the allocation being targeted by this request.\n\tAllocID string\n\n\t// TaskName is the name of the task being targeted by this request.\n\tTaskName string\n\n\t// State is the state to apply to the task being targeted by this request.\n\tScheduleState TaskScheduleState\n}\n\nfunc (r *ScheduleStateApplyRequest) Validate() error {\n\tif r.AllocID == \"\" {\n\t\treturn errors.New(\"alloc id must be set\")\n\t}\n\n\tif r.TaskName == \"\" {\n\t\treturn errors.New(\"task name must be set\")\n\t}\n\n\tswitch r.ScheduleState {\n\tcase TaskScheduleStateRun:\n\tcase TaskScheduleStateForceRun:\n\tcase TaskScheduleStateSchedPause:\n\tcase TaskScheduleStateForcePause:\n\tdefault:\n\t\treturn errors.New(\"not a valid task schedule state\")\n\t}\n\n\treturn nil\n}\n","sourceCodeStart":411,"sourceCodeEnd":447,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/nomad/structs/node.go#L411-L447","documentation":"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).","triggerScenarios":"Submitting a ScheduleStateApplyRequest (task schedule state API) with r.AllocID == \"\"; caused by a caller that never populated the allocation ID after resolving the task.","commonSituations":"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.","solutions":["Populate AllocID with the target allocation's UUID before calling Validate/Apply","Resolve the allocation ID via the allocations list API for the job/task first","Fail fast client-side when allocation lookup yields no ID instead of sending an empty request","Check upstream code paths for swallowed errors that leave AllocID unset"],"exampleFix":"// before\nreq := &structs.ScheduleStateApplyRequest{\n  TaskName: \"redis\",\n  ScheduleState: structs.TaskScheduleStateSchedPause,\n}\n\n// after\nreq := &structs.ScheduleStateApplyRequest{\n  AllocID: allocID, // e.g. \"e5f0b1c2-...\"\n  TaskName: \"redis\",\n  ScheduleState: structs.TaskScheduleStateSchedPause,\n}","handlingStrategy":"validation","validationCode":"if req.AllocID == \"\" {\n\treturn errors.New(\"alloc id required before applying schedule state\")\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Resolve alloc ID via API before scheduling-state calls","Check for swallowed lookup errors upstream","Require alloc ID explicitly in tooling CLIs"],"tags":["nomad","task-scheduling","validation","required-field"],"backgroundTag":"missing-required-argument","analyzedSha":"482b49bf1aec006f089bcfc7e632d8f6ac303e5e","analyzedAt":"2026-09-04T07:54:14.808Z","contentChangedAt":"2026-09-04T07:54:14.808Z","schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}