hashicorp/nomad · warning

must provide a file path

Error message

must provide a file path

What it means

pathNotPresentErr is a sentinel error returned by the client FS stream endpoint when the request's Path field is empty. Streaming a file requires an absolute path inside the allocation. Returned to the stream encoder with HTTP 400 Bad Request.

Source

Thrown at client/fs_endpoint.go:34

	"strconv"
	"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

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Supply the path query parameter with an absolute file path inside the allocation (e.g. /alloc/logs/app.stdout.0)
2. If building the request in code, set req.Path explicitly before calling Stream
3. Check URL construction for dropped/empty query parameters (log the final URL)

Example fix

// before
GET /v1/client/fs/stream/<alloc_id>?origin=start
// after
GET /v1/client/fs/stream/<alloc_id>?path=/alloc/logs/app.stdout.0&origin=start

if path == "" {
    return nil, fmt.Errorf("path is required for streaming; e.g. /alloc/logs/<task>.stdout.0")
}

func hasPath(req *cstructs.FsStreamRequest) bool {
    return req != nil && req.Path != ""
}

err := streamFile(ctx, alloc, path)
if err != nil && strings.Contains(err.Error(), "must provide a file path") {
    log.Printf("no path supplied, defaulting to /alloc/logs/%s.stdout.0", task)
    return streamFile(ctx, alloc, fmt.Sprintf("/alloc/logs/%s.stdout.0", task))
}

When it happens

Trigger: Calling the Stream (fs stream) endpoint with req.Path == "" — e.g. GET /v1/client/fs/stream/<alloc> without the ?path= query parameter.

Common situations: API consumers following the logs endpoint pattern but forgetting that stream requires an explicit file path; automation omitting the path after URL-encoding bugs drop it; empty variable interpolated into the path 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

• must provide a valid alloc id
• missing policy name
• Unknown log level
• command is not present
• unknown task name %q

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