hashicorp/nomad · error

Payload exceeds maximum size; %d > %d

Error message

Payload exceeds maximum size; %d > %d

What it means

Dispatch payloads are capped at DispatchPayloadSizeLimit (16 KiB) for performance and Raft entry-size reasons. If the submitted payload exceeds that byte length, the dispatch is rejected with the actual and maximum sizes.

Source

Thrown at nomad/job_endpoint.go:2143

	}

	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{}{}
	}

	required := set.From(job.ParameterizedJob.MetaRequired)
	optional := set.From(job.ParameterizedJob.MetaOptional)

	// Check the metadata key constraints are met
	unpermitted := make(map[string]struct{})
	for k := range req.Meta {
		req := required.Contains(k)

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Shrink the payload below 16384 bytes; send a reference (S3/GCS path, artifact URL) instead of the data
2. Compress the data if feasible, keeping the encoded size under the limit
3. Move bulk data to external storage and pass only identifiers via meta

Example fix

// before
cat big-blob.json | nomad job dispatch batch-process   # 120KB
// after
S3_URL=$(upload_to_s3 big-blob.json)
echo "$S3_URL" | nomad job dispatch batch-process

const maxPayload = 16384
if len(payload) > maxPayload {
    return fmt.Errorf("payload is %d bytes; limit is %d", len(payload), maxPayload)
}

When it happens

Trigger: Dispatching with a Payload whose len() exceeds 16384 bytes (e.g. large JSON blobs, files piped via stdin).

Common situations: Piping large files into `nomad job dispatch`; serializing big configs into the payload instead of passing an object-store reference; growing payload content over time until it crosses the 16KiB limit.

Related errors

• Payload is not provided but required by parameterized job
• Payload provided but forbidden by parameterized job
• variables are limited to 64KiB in total size
• 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/589ca65bcc416cc5. Report an issue: GitHub.