hashicorp/nomad · error

missing job ID

Error message

missing job ID

What it means

Job.Allocations was called without JobID set. The endpoint deliberately rejects empty JobIDs because the query would return no allocations and could mask request-construction bugs, so it fails fast with 'missing job ID'.

Source

Thrown at nomad/job_endpoint.go:1521

		return err
	}
	j.srv.MeasureRPCRate("job", structs.RateMetricList, args)
	if authErr != nil {
		return structs.ErrPermissionDenied
	}
	defer metrics.MeasureSince([]string{"nomad", "job", "allocations"}, time.Now())

	// Check for read-job permissions
	if aclObj, err := j.srv.ResolveACL(args); err != nil {
		return err
	} else if !aclObj.AllowNsOp(args.RequestNamespace(), acl.NamespaceCapabilityReadJob) {
		return structs.ErrPermissionDenied
	}

	// Ensure JobID is set otherwise everything works and never returns
	// allocations which can hide bugs in request code.
	if args.JobID == "" {
		return fmt.Errorf("missing job ID")
	}

	// Setup the blocking query
	opts := blockingOptions{
		queryOpts: &args.QueryOptions,
		queryMeta: &reply.QueryMeta,
		run: func(ws memdb.WatchSet, state *state.StateStore) error {
			// Capture the allocations
			allocs, err := state.AllocsByJob(ws, args.RequestNamespace(), args.JobID, args.All)
			if err != nil {
				return err
			}

			// Convert to stubs
			if len(allocs) > 0 {
				reply.Allocations = make([]*structs.AllocListStub, 0, len(allocs))
				for _, alloc := range allocs {
					reply.Allocations = append(reply.Allocations, alloc.Stub(nil))

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Set JobID in the request before calling the allocations endpoint.
2. Resolve the job ID from 'nomad job status' or the jobs list API if it comes from automation.
3. Add a client-side empty-string check so failures surface at the call site, not the server.
4. Check the templating/env pipeline that supplies the job ID for silent empty values.

Example fix

// before
allocs, _, err := client.Jobs().Allocations("", false, nil)
// after
if jobID == "" {
    return fmt.Errorf("job ID is required")
}
allocs, _, err := client.Jobs().Allocations(jobID, false, nil)

if jobID == "" {
    return fmt.Errorf("cannot list allocations: jobID is empty")
}
allocs, _, err := client.Jobs().Allocations(jobID, all, nil)

func jobIDSet(id string) bool { return strings.TrimSpace(id) != "" }

allocs, _, err := client.Jobs().Allocations(jobID, false, nil)
if err != nil && strings.Contains(err.Error(), "missing job ID") {
    return fmt.Errorf("check the job-id flag/env: got empty value")
}

When it happens

Trigger: GET /v1/job//allocations or client.Jobs().Allocations(jobID="", ...) — any AllocsRequest with args.JobID == "" after ACL/namespace checks pass, at nomad/job_endpoint.go:1521.

Common situations: Variable holding the job ID is empty due to a failed template or unset env var; CLI flag omitted and default is empty string; REST client concatenating an empty path segment; pagination code dropping the ID field.

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

• JobID required for actions
• Job required for plan
• missing node ID
• Missing allocation ID
• Filter expression cannot be used with other filter parameter

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