hashicorp/nomad · warning

must provide a valid alloc id

Error message

must provide a valid alloc id

What it means

allocIDNotPresentErr is a sentinel error in the client's filesystem endpoint signaling that a request arrived with an empty AllocID. Every FS operation (logs, stream, stat, list, exec) requires an allocation ID to route to the correct alloc runner. It is returned with HTTP 400 Bad Request.

Source

Thrown at client/fs_endpoint.go:33

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

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Populate AllocID (or the alloc_id query parameter) with a valid allocation ID from nomad job status <job>
2. Verify the HTTP request actually includes the parameter and it isn't stripped by a proxy/template
3. Confirm the allocation ID string is non-empty before invoking the client API in your code

Example fix

// before
req := &cstructs.FsStreamRequest{Path: "/logs/foo.log", Origin: "start"}
// after
req := &cstructs.FsStreamRequest{AllocID: alloc.ID, Path: "/logs/foo.log", Origin: "start"}

if allocID == "" {
    return nil, fmt.Errorf("allocID is required: run 'nomad job status <job>' to obtain one")
}

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

resp, err := client.FS().Logs(ctx, alloc, "web", false, "stdout", "start", 0, false, nil)
if err != nil && strings.Contains(err.Error(), "must provide a valid alloc id") {
    log.Printf("request rejected: alloc ID missing — re-resolve allocation: %v", err)
    alloc = resolveAlloc()
    return client.FS().Logs(ctx, alloc, "web", false, "stdout", "start", 0, false, nil)
}

When it happens

Trigger: Calling Logs, Stream, execImpl, DirectoryListRequest, FileStatRequest, or FileReadAtRequest with req.AllocID == "" — e.g. an API client omitting the ?alloc_id= parameter or building a structs request with a zero-value AllocID.

Common situations: Custom tooling calling /v1/client/fs/... endpoints without the alloc ID query param; a caller using an uninitialized struct; UI/API layer dropping the alloc ID during request forwarding.

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 file path
• 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/cb74c6a335f95c10. Report an issue: GitHub.