hashicorp/nomad · error

Payload is not provided but required by parameterized job

Error message

Payload is not provided but required by parameterized job

What it means

validateDispatchRequest enforces the parameterized job's payload constraint. If the job declares payload = "required" in its parameterized stanza but the dispatch request carries no (empty) payload, the dispatch is rejected.

Source

Thrown at nomad/job_endpoint.go:2136

	reply.JobCreateIndex = jobCreateIndex
	reply.DispatchedJobID = dispatchJob.ID
	reply.Index = jobCreateIndex

	if eval != nil {
		reply.EvalID = eval.ID
		reply.EvalCreateIndex = jobCreateIndex
	}

	return nil
}

// validateDispatchRequest returns whether the request is valid given the
// parameterized job.
func validateDispatchRequest(req *structs.JobDispatchRequest, job *structs.Job, config *Config) error {
	// Check the payload constraint is met
	hasInputData := len(req.Payload) != 0
	if job.ParameterizedJob.Payload == structs.DispatchPayloadRequired && !hasInputData {
		return fmt.Errorf("Payload is not provided but required by parameterized job")
	} else if job.ParameterizedJob.Payload == structs.DispatchPayloadForbidden && hasInputData {
		return fmt.Errorf("Payload provided but forbidden by parameterized job")
	}

	// Check the payload doesn't exceed the size limit
	if l := len(req.Payload); l > DispatchPayloadSizeLimit {
		return fmt.Errorf("Payload exceeds maximum size; %d > %d", l, DispatchPayloadSizeLimit)
	}

	// Check if the metadata is a set
	keys := make(map[string]struct{}, len(req.Meta))
	for k := range req.Meta {
		if _, ok := keys[k]; ok {
			return fmt.Errorf("Duplicate key %q in passed metadata", k)
		}
		keys[k] = struct{}{}
	}

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Provide a payload: `echo <data> | nomad job dispatch <job-id>` or set Payload in the request
2. If payload is unnecessary, change the job spec to `payload = "optional"` or "forbidden" and resubmit
3. Update automation to always attach required payload bytes

Example fix

// before
nomad job dispatch batch-process
// after
echo '{"input":true}' | nomad job dispatch batch-process

if *job.ParameterizedJob.Payload == "required" && len(payload) == 0 {
    return fmt.Errorf("job %s requires a payload", jobID)
}

When it happens

Trigger: Dispatching a parameterized job with `parameterized { payload = "required" }` while passing an empty Payload in JobDispatchRequest (or no stdin/body via `nomad job dispatch`).

Common situations: CLI dispatch invoked without piping payload data (`nomad job dispatch job` with no stdin); automation that omits the payload for jobs recently switched from optional to required.

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

• Payload provided but forbidden by parameterized job
• Payload exceeds maximum size; %d > %d
• Dispatch request included unpermitted metadata keys: %v
• unknown task name %q
• must specify at least one healthy/unhealthy allocation ID

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