hashicorp/nomad · error

unknown task name %q

Error message

unknown task name %q

What it means

The logs endpoint validates the requested task name against the allocation's TaskStates map. If no task state exists for the given name, the endpoint returns HTTP 400 with this message. This is a request-side naming error, not an infrastructure failure.

Source

Thrown at client/fs_endpoint.go:437

		return
	}

	allocState, err := f.c.GetAllocState(req.AllocID)
	if err != nil {
		code := new(int64(http.StatusInternalServerError))
		if structs.IsErrUnknownAllocation(err) {
			code = new(int64(http.StatusNotFound))
		}

		handleStreamResultError(err, code, encoder)
		return
	}

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

	if taskState.StartedAt.IsZero() {
		handleStreamResultError(
			fmt.Errorf("task %q not started yet. No logs available", req.Task),
			new(int64(http.StatusNotFound)),
			encoder)
		return
	}

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

	frames := make(chan *sframer.StreamFrame, streamFramesBuffer)
	errCh := make(chan error)

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Use the exact task name from the job spec (check alloc.TaskNames / alloc.TaskStates via the API).
2. Fetch the allocation with Allocations().Info and pick a task name from TaskStates before calling the logs API.
3. Fix typos and case mismatches in the task parameter; names are case-sensitive.

Example fix

// before
logs, err := client.Allocs().Logs(alloc, false, "Web", "stdout", nil, nil)
// after
names, _, err := client.Allocations().TaskNames(alloc.ID, nil)
if err != nil || len(names) == 0 {
    return err
}
logs, err = client.Allocs().Logs(alloc, false, names[0], "stdout", nil, nil)

a, _, err := client.Allocations().Info(allocID, nil)
if err != nil {
    return err
}
if _, ok := a.TaskStates[taskName]; !ok {
    return fmt.Errorf("task %q not in alloc; valid: %v", taskName, keys(a.TaskStates))
}

func taskExists(a *api.Allocation, task string) bool {
    return a != nil && a.TaskStates != nil && a.TaskStates[task] != nil
}

if err := fetchLogs(task); err != nil {
    if strings.Contains(err.Error(), "unknown task name") {
        return fmt.Errorf("fix task name; see alloc.TaskStates")
    }
    return err
}

When it happens

Trigger: Calling GET /v1/client/fs/logs (or client.Allocs().Logs) with a task parameter that does not match any task in the allocation's task group — typo, wrong case, or a task name from a different group/job version.

Common situations: Copy-pasting a task name across job files; renaming a task in the job spec while log tooling still uses the old name; passing the group name instead of the task name; job versions where the task list changed.

Related errors

• file %q is a directory
• task %q not started yet. No logs available
• failed to list entries: %v
• failed to stream %q: %v
• unable to determine remaining read limit

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