hashicorp/nomad · warning

must provide task name

Error message

must provide task name

What it means

taskNotPresentErr is a sentinel error for requests that omit the Task name. Log retrieval and exec both operate on a specific task within the allocation, so Task must be non-empty. Returned with HTTP 400 from both client/fs_endpoint.go and client/alloc_endpoint.go paths.

Source

Thrown at client/fs_endpoint.go:35

	"strings"
	"syscall"
	"time"

	metrics "github.com/hashicorp/go-metrics/compat"
	"github.com/hashicorp/go-msgpack/v2/codec"
	"github.com/hpcloud/tail/watch"

	"github.com/hashicorp/nomad/acl"
	"github.com/hashicorp/nomad/client/allocdir"
	sframer "github.com/hashicorp/nomad/client/lib/streamframer"
	cstructs "github.com/hashicorp/nomad/client/structs"
	"github.com/hashicorp/nomad/nomad/structs"
)

var (
	allocIDNotPresentErr = fmt.Errorf("must provide a valid alloc id")
	pathNotPresentErr    = fmt.Errorf("must provide a file path")
	taskNotPresentErr    = fmt.Errorf("must provide task name")
	logTypeNotPresentErr = fmt.Errorf("must provide log type (stdout/stderr)")
	invalidOrigin        = fmt.Errorf("origin must be start or end")
)

const (
	// streamFramesBuffer is the number of stream frames that will be buffered
	// before back pressure is applied on the stream framer.
	streamFramesBuffer = 32

	// streamFrameSize is the maximum number of bytes to send in a single frame
	streamFrameSize = 64 * 1024

	// streamHeartbeatRate is the rate at which a heartbeat will occur to detect
	// a closed connection without sending any additional data
	streamHeartbeatRate = 1 * time.Second

	// streamBatchWindow is the window in which file content is batched before
	// being flushed if the frame size has not been hit.

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Add the task query parameter (or req.Task field) naming a task in the allocation
2. Look up valid task names via nomad alloc status <alloc_id> and pass one explicitly
3. In code, validate req.Task != "" before invoking the endpoint

Example fix

// before
GET /v1/client/fs/logs/<alloc_id>?type=stdout
// after
GET /v1/client/fs/logs/<alloc_id>?task=web&type=stdout

tasks, _, err := client.Allocations().Tasks(alloc, nil)
if err != nil {
    return err
}
if task == "" {
    if len(tasks) == 1 {
        task = tasks[0].Name
    } else {
        return fmt.Errorf("task is required; allocation has tasks: %v", taskNames(tasks))
    }
}

func hasTask(req *cstructs.FsLogsRequest) bool {
    return req != nil && req.Task != ""
}

logs, err := client.AllocFS().Logs(alloc, "web", "", false, "stdout", "start", 0, nil, nil)
if err != nil && strings.Contains(err.Error(), "must provide task name") {
    return fmt.Errorf("specify -task; alloc %s contains multiple tasks", alloc.ID)
}

When it happens

Trigger: Calling logs, Logs, or execImpl with req.Task == "" — e.g. /v1/client/fs/logs/<alloc> without ?task= or an exec request built without the task field.

Common situations: Tooling that assumes single-task allocations and skips the task parameter; group jobs with multiple tasks where the UI variable for task is unset; hand-rolled HTTP calls missing the query param.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• command is not present
• unknown task name %q
• must provide log type (stdout/stderr)
• origin must be start or end
• missing policy name

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