hashicorp/nomad · error

missing job ID for deregistering

Error message

missing job ID for deregistering

What it means

The Job.Deregister RPC validates that a JobID is present before looking up the job; an empty ID cannot identify anything to remove, so Nomad rejects the request with this message. It is a pure request-validation failure thrown before any Raft write.

Source

Thrown at nomad/job_endpoint.go:809

	// Check for submit-job permissions
	aclObj, err := j.srv.ResolveACL(args)
	if err != nil {
		return err
	}

	permissionsCheck := []string{acl.NamespaceCapabilitySubmitJob, acl.NamespaceCapabilityPurgeJob}
	if !args.Purge {
		permissionsCheck = append(permissionsCheck, acl.NamespaceCapabilityDeregisterJob)
	}

	if !aclObj.AllowNsOpAnyOf(args.RequestNamespace(), permissionsCheck...) {
		return structs.ErrPermissionDenied
	}

	// Validate the arguments
	if args.JobID == "" {
		return fmt.Errorf("missing job ID for deregistering")
	}

	// Lookup the job
	snap, err := j.srv.fsm.State().Snapshot()
	if err != nil {
		return err
	}
	ws := memdb.NewWatchSet()
	job, err := snap.JobByID(ws, args.RequestNamespace(), args.JobID)
	if err != nil {
		return err
	}
	if job == nil {
		return nil
	}

	var eval *structs.Evaluation

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Set JobID in the JobDeregisterRequest or use client.Jobs().Deregister(id, purge, nil)
2. Fail fast in scripts if the job ID variable is empty before calling the API
3. Validate non-empty input at the automation layer before issuing the DELETE

Example fix

// before
if os.Getenv("JOB") == "" { os.Exit(0) }
client.Jobs().Deregister(os.Getenv("JOB"), false, nil)
// after
jobID := os.Getenv("JOB")
if jobID == "" { return fmt.Errorf("JOB must be set") }
client.Jobs().Deregister(jobID, false, nil)

if jobID == "" {
	return fmt.Errorf("refusing to deregister: empty job ID")
}

When it happens

Trigger: POST /v1/job/<id> with method DELETE where the request body JobID is empty — usually a hand-built JobDeregisterRequest or a wrapper that fails to copy the ID from the URL path.

Common situations: Custom API clients building the deregister payload without JobID; shell scripts with an unexpanded variable (empty $JOB_ID); SDK misuse bypassing the Jobs().Deregister convenience method.

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

• missing secret ID
• namespace cannot contain template delimiters or parenthesis
• wait config is nil or empty
• CSI.ControllerAttachVolume: VolumeID is required
• CSI.ControllerAttachVolume: ClientCSINodeID is required

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