hashicorp/nomad · error

Error restarting allocation %q: %s

Error message

Error restarting allocation %q: %s

What it means

handleAlloc wraps any failure from restarting an allocation (task-level restart errors, nested multierrors) behind 'Error restarting allocation <id>: ...', using multierror.Prefix to flatten nested errors for readability.

Source

Thrown at command/job_restart.go:870

// handleAlloc stops or restarts an allocation in-place. Blocks until the
// allocation  is done restarting or the rescheduled allocation is running.
func (c *JobRestartCommand) handleAlloc(alloc AllocationListStubWithJob) error {
	var err error
	if c.reschedule {
		// Stopping an allocation triggers a reschedule.
		err = c.stopAlloc(alloc)
	} else {
		err = c.restartAlloc(alloc)
	}
	if err != nil {
		msg := fmt.Sprintf("Error restarting allocation %q:", limit(alloc.ID, c.length))
		if mErr, ok := err.(*multierror.Error); ok {
			// Unwrap the errors and prefix them with a common message to
			// prevent deep nesting of errors.
			return multierror.Prefix(mErr, msg)
		}
		return fmt.Errorf("%s %w", msg, err)
	}
	return nil
}

// restartAlloc restarts an allocation in place and blocks until the tasks are
// done restarting.
func (c *JobRestartCommand) restartAlloc(alloc AllocationListStubWithJob) error {
	shortAllocID := limit(alloc.ID, c.length)

	if c.allTasks {
		c.Ui.Output(fmt.Sprintf(
			"    %s: Restarting all tasks in allocation %q for group %q",
			formatTime(time.Now()),
			shortAllocID,
			alloc.TaskGroup,
		))

		return c.client.Allocations().RestartAllTasks(&api.Allocation{ID: alloc.ID}, nil)

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Check nomad alloc status <alloc-id> and the agent logs for the root cause
2. Verify the ACL token has allocation lifecycle permissions (acl:write or alloc-lifecycle)
3. Confirm the Nomad agent address is reachable (NOMAD_ADDR) and healthy
4. Re-run the restart; transient API failures can be retried

alloc, _, err := client.Allocations().Info(allocID, nil)
if err != nil || alloc.ClientStatus == "complete" || alloc.ClientStatus == "failed" {
    return fmt.Errorf("alloc %s not restartable: clientStatus=%s", allocID, alloc.ClientStatus)
}

func isRestartable(a *api.Allocation) bool {
    return a != nil && a.ClientStatus == "running"
}

if err := cmd.handleAlloc(alloc); err != nil {
    var merr *multierror.Error
    if errors.As(err, &merr) {
        for _, e := range merr.Errors { log.Println(e) }
    } else {
        log.Printf("restart failed: %v", err)
    }
}

When it happens

Trigger: api.Allocations().Restart fails or returns task errors while the job restart command restarts an alloc in place; errors are bubbled up prefixed with the (truncated) alloc ID.

Common situations: Nomad agent unreachable or client API errors; alloc already terminal/complete; task driver failures during in-place restart; ACL token lacking alloc-lifecycle permissions.

Related errors

• allocation not found
• Failed to restart task %q: %w
• Failed to stop allocation: %w
• missing AllocID
• unknown task name %q

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