What causes "task name cannot be set when restarting all tasks" in hashicorp/nomad?

Pass an empty string for taskName when allTasks is true.

task name cannot be set when restarting all tasks

Error message

task name cannot be set when restarting all tasks

What it means

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.

Source

Thrown at client/client.go:1116

	}
	return ar.GetTaskPauseState(task)
}

// CollectAllocation garbage collects a single allocation on a node. Returns
// true if alloc was found and garbage collected; otherwise false.
func (c *Client) CollectAllocation(allocID string) bool {
	return c.garbageCollector.Collect(allocID)
}

// CollectAllAllocs garbage collects all allocations on a node in the terminal
// state
func (c *Client) CollectAllAllocs() {
	c.garbageCollector.CollectAll()
}

func (c *Client) RestartAllocation(allocID, taskName string, allTasks bool) error {
	if allTasks && taskName != "" {
		return fmt.Errorf("task name cannot be set when restarting all tasks")
	}

	ar, err := c.getAllocRunner(allocID)
	if err != nil {
		return err
	}

	if taskName != "" {
		event := structs.NewTaskEvent(structs.TaskRestartSignal).
			SetRestartReason("User requested task to restart")
		return ar.RestartTask(taskName, event)
	}

	if allTasks {
		event := structs.NewTaskEvent(structs.TaskRestartSignal).
			SetRestartReason("User requested all tasks to restart")
		return ar.RestartAll(event)
	}

View on GitHub (pinned to 482b49bf1a)

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.

Example fix

// before
client.RestartAllocation(allocID, "web", true)
// after
client.RestartAllocation(allocID, "", true)      // restart all
// or
client.RestartAllocation(allocID, "web", false)  // restart one task

Defensive patterns

Strategy: validation

Validate before calling

func validateRestartArgs(taskName string, allTasks bool) error {
    if allTasks && taskName != "" {
        return errors.New("task name cannot be set when restarting all tasks")
    }
    if !allTasks && taskName == "" {
        return errors.New("task name required when not restarting all tasks")
    }
    return nil
}

Try / catch

if err := client.RestartAllocation(allocID, taskName, allTasks); err != nil {
    if strings.Contains(err.Error(), "task name cannot be set when restarting all tasks") {
        // fix call-site arguments; safe to retry after correction (no state mutated)
    }
}

Prevention

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

When it happens

Trigger: 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).

Common situations: 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.

Related errors

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