What causes "unknown task name %q" in hashicorp/nomad?

List the allocation's tasks with `nomad alloc status ` and use an exact task name in req.Task

unknown task name %q

Error message

unknown task name %q

What it means

Nomad's client exec endpoint validates that the task name supplied in an exec request actually exists in the allocation's task state map before attempting to run a command. When req.Task does not match any task name in the allocation, execImpl returns HTTP 400 with this message. It is a request-validation error, not an internal failure.

Source

Thrown at client/alloc_endpoint.go:355

		if !exec {
			return nil, nstructs.ErrPermissionDenied
		}
	}

	allocState, err := a.c.GetAllocState(req.AllocID)
	if err != nil {
		code := new(int64(500))
		if nstructs.IsErrUnknownAllocation(err) {
			code = new(int64(404))
		}

		return code, err
	}

	// Check that the task is there
	taskState := allocState.TaskStates[req.Task]
	if taskState == nil {
		return new(int64(400)), fmt.Errorf("unknown task name %q", req.Task)
	}

	if taskState.StartedAt.IsZero() {
		return new(int64(404)), fmt.Errorf("task %q not started yet.", req.Task)
	}

	ctx, cancel := context.WithCancel(context.Background())
	defer cancel()

	h := ar.GetTaskExecHandler(req.Task)
	if h == nil {
		return new(int64(404)), fmt.Errorf("task %q is not running.", req.Task)
	}

	err = h(ctx, req.Cmd, req.Tty, newExecStream(decoder, encoder))
	if err != nil {
		code := new(int64(500))
		return code, err

View on GitHub (pinned to 482b49bf1a)

Solutions

List the allocation's tasks with `nomad alloc status <alloc-id>` and use an exact task name in req.Task
Fix the task name typo in the command/script
If the task was renamed, redeploy scripts with the new name or pin to the old allocation
Verify you are exec'ing into the allocation that actually contains the task

Example fix

// before
client.Exec(allocID, "sidecar", []string{"ls"})
// after
alloc, _, _ := client.Allocations().Info(allocID, nil)
taskName := alloc.TaskGroup // or alloc.NamedTaskGroupStates key actually present
client.Exec(allocID, taskName, []string{"ls"})

Defensive patterns

Strategy: validation

Validate before calling

alloc, _, err := client.Allocations().Info(allocID, nil)
if err != nil { return err }
ts, ok := alloc.TaskStates[taskName]
if !ok { return fmt.Errorf("alloc %s has no task %q", allocID, taskName) }

Type guard

func hasTask(alloc *api.Allocation, task string) bool {
  _, ok := alloc.TaskStates[task]
  return ok
}

Prevention

Derive task names from alloc.TaskStates rather than hardcoding
Validate task names in scripts with `nomad alloc status`
Use a single source of truth for task names shared between job spec and tooling

When it happens

Trigger: Calling the alloc exec API (via nomad alloc exec or the HTTP exec endpoint) with a task name that is not one of the tasks in the target allocation — e.g. a typo, a task from a different job, or a task that was removed in a later task-group version.

Common situations: Typo'd task names in scripts or CI; using the old task name after a job update renamed the task; exec'ing into a group-level allocation while specifying a task belonging to another group; autocomplete/scripts assuming a default task name.

Related errors

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