What causes "missing allocation ID" in hashicorp/nomad?

Set args.AllocID to the allocation UUID before calling List.

missing allocation ID

Error message

missing allocation ID

What it means

The FileSystem.List RPC (reading an allocation's sandbox directory listing) validates args.AllocID after ACL checks. An empty AllocID cannot identify which allocation's filesystem to list, so "missing allocation ID" is returned before the state lookup. Note this variant uses the wording "missing allocation ID" rather than "missing AllocID".

Source

Thrown at nomad/client_fs_endpoint.go:125

	// the Node registration and the cost is fairly high for adding another hope
	// in the forwarding chain.
	args.QueryOptions.AllowStale = true

	authErr := f.srv.Authenticate(nil, args)

	// Potentially forward to a different region.
	if done, err := f.srv.forward("FileSystem.List", args, args, reply); done {
		return err
	}
	f.srv.MeasureRPCRate("file_system", structs.RateMetricList, args)
	if authErr != nil {
		return structs.ErrPermissionDenied
	}
	defer metrics.MeasureSince([]string{"nomad", "file_system", "list"}, time.Now())

	// Verify the arguments.
	if args.AllocID == "" {
		return errors.New("missing allocation ID")
	}

	// Lookup the allocation
	snap, err := f.srv.State().Snapshot()
	if err != nil {
		return err
	}

	alloc, err := getAlloc(snap, args.AllocID)
	if err != nil {
		return err
	}

	// Check namespace filesystem read permissions
	allowNsOp := acl.NamespaceValidator(acl.NamespaceCapabilityReadFS)
	aclObj, err := f.srv.ResolveACL(args)
	if err != nil {
		return err

View on GitHub (pinned to 482b49bf1a)

Solutions

Set args.AllocID to the allocation UUID before calling List.
Obtain the alloc ID from the job allocations API or `nomad job allocs`.
Validate AllocID non-empty before the RPC call.

Example fix

// before
args := structs.AllocListRequest{Path: "/logs"}
err := fs.List(args, &reply)
// after
args := structs.AllocListRequest{AllocID: alloc.ID, Path: "/logs"}
err := fs.List(args, &reply)

Defensive patterns

Strategy: validation

Validate before calling

if allocID == "" {
    return fmt.Errorf("FS List requires a non-empty AllocID")
}

Type guard

func canListFS(args *structs.AllocListRequest) bool {
    return args != nil && args.AllocID != "" && args.Path != ""
}

Prevention

Always set AllocID when building FS requests.
In CLIs, require the alloc ID argument and error out before dialing if empty.
Cache alloc IDs from lookups instead of relying on ambient variables.

When it happens

Trigger: Calling ClientFileSystem.List with structs.AllocListRequest where AllocID is "".

Common situations: Custom log/file browsing tools against the FS API with an empty alloc ID; CLI built on the FS endpoints where a positional arg was omitted; zero-valued request structs in automation.

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

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