{"record":{"id":"e26d9851ab937057","repo":"hashicorp/nomad","slug":"task-name-cannot-be-set-when-restarting-all-tasks","errorCode":null,"errorMessage":"task name cannot be set when restarting all tasks","messagePattern":"task name cannot be set when restarting all tasks","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"client/client.go","lineNumber":1116,"sourceCode":"\t}\n\treturn ar.GetTaskPauseState(task)\n}\n\n// CollectAllocation garbage collects a single allocation on a node. Returns\n// true if alloc was found and garbage collected; otherwise false.\nfunc (c *Client) CollectAllocation(allocID string) bool {\n\treturn c.garbageCollector.Collect(allocID)\n}\n\n// CollectAllAllocs garbage collects all allocations on a node in the terminal\n// state\nfunc (c *Client) CollectAllAllocs() {\n\tc.garbageCollector.CollectAll()\n}\n\nfunc (c *Client) RestartAllocation(allocID, taskName string, allTasks bool) error {\n\tif allTasks && taskName != \"\" {\n\t\treturn fmt.Errorf(\"task name cannot be set when restarting all tasks\")\n\t}\n\n\tar, err := c.getAllocRunner(allocID)\n\tif err != nil {\n\t\treturn err\n\t}\n\n\tif taskName != \"\" {\n\t\tevent := structs.NewTaskEvent(structs.TaskRestartSignal).\n\t\t\tSetRestartReason(\"User requested task to restart\")\n\t\treturn ar.RestartTask(taskName, event)\n\t}\n\n\tif allTasks {\n\t\tevent := structs.NewTaskEvent(structs.TaskRestartSignal).\n\t\t\tSetRestartReason(\"User requested all tasks to restart\")\n\t\treturn ar.RestartAll(event)\n\t}","sourceCodeStart":1098,"sourceCodeEnd":1134,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/client/client.go#L1098-L1134","documentation":"Client.RestartAllocation validates its arguments: when allTasks is true, taskName must be empty, since restarting all tasks is mutually exclusive with naming a single task. Passing both returns this plain error without touching any allocation.","triggerScenarios":"Calling Client.RestartAllocation(allocID, taskName, true) — i.e. allTasks=true with a non-empty taskName (e.g. via the agent local API `nomad alloc restart -all -task X <alloc>` semantics wired through this method).","commonSituations":"Tooling or scripts that fill in a default task name while also requesting a full-allocation restart; mixing the -all flag with a -task flag in automation around the client API.","solutions":["Pass an empty string for taskName when allTasks is true.","Pass allTasks=false when you intend to restart a specific task by name.","Validate arguments at the call site before invoking RestartAllocation."],"exampleFix":"// before\nclient.RestartAllocation(allocID, \"web\", true)\n// after\nclient.RestartAllocation(allocID, \"\", true)      // restart all\n// or\nclient.RestartAllocation(allocID, \"web\", false)  // restart one task","handlingStrategy":"validation","validationCode":"func validateRestartArgs(taskName string, allTasks bool) error {\n    if allTasks && taskName != \"\" {\n        return errors.New(\"task name cannot be set when restarting all tasks\")\n    }\n    if !allTasks && taskName == \"\" {\n        return errors.New(\"task name required when not restarting all tasks\")\n    }\n    return nil\n}","typeGuard":null,"tryCatchPattern":"if err := client.RestartAllocation(allocID, taskName, allTasks); err != nil {\n    if strings.Contains(err.Error(), \"task name cannot be set when restarting all tasks\") {\n        // fix call-site arguments; safe to retry after correction (no state mutated)\n    }\n}","preventionTips":["Wrap RestartAllocation in a helper that enforces argument exclusivity","In CLI/automation code, reject -task together with -all before calling the API","Validate arguments at every call site before invoking client methods"],"tags":["validation","api-usage","restart-allocation"],"backgroundTag":"mutually-exclusive-arguments","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"}