hashicorp/nomad · error

Unknown payload requirement: %q

Error message

Unknown payload requirement: %q

What it means

ParameterizedJobConfig.Validate checks that the dispatch payload requirement is one of the allowed constants: DispatchPayloadOptional, DispatchPayloadRequired, or DispatchPayloadForbidden. Any other value produces this error appended to the validation multierror. It guards the parameterized job's `dispatch_payload` configuration.

Source

Thrown at nomad/structs/structs.go:6089

// ParameterizedJobConfig is used to configure the parameterized job
type ParameterizedJobConfig struct {
	// Payload configure the payload requirements
	Payload string

	// MetaRequired is metadata keys that must be specified by the dispatcher
	MetaRequired []string

	// MetaOptional is metadata keys that may be specified by the dispatcher
	MetaOptional []string
}

func (d *ParameterizedJobConfig) Validate() error {
	var mErr multierror.Error
	switch d.Payload {
	case DispatchPayloadOptional, DispatchPayloadRequired, DispatchPayloadForbidden:
	default:
		_ = multierror.Append(&mErr, fmt.Errorf("Unknown payload requirement: %q", d.Payload))
	}

	// Check that the meta configurations are disjoint sets
	disjoint, offending := helper.IsDisjoint(d.MetaRequired, d.MetaOptional)
	if !disjoint {
		_ = multierror.Append(&mErr, fmt.Errorf("Required and optional meta keys should be disjoint. Following keys exist in both: %v", offending))
	}

	return mErr.ErrorOrNil()
}

func (d *ParameterizedJobConfig) Canonicalize() {
	if d.Payload == "" {
		d.Payload = DispatchPayloadOptional
	}
}

func (d *ParameterizedJobConfig) Copy() *ParameterizedJobConfig {

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Set the payload value to exactly one of "optional", "required", or "forbidden".
2. Remove the field to rely on the default behavior if unsure.
3. Run `nomad job validate` to catch the invalid value before registration.
4. Check string casing — matching is exact.

Example fix

// before
dispatch_payload {
  payload = "Maybe"
}
// after
dispatch_payload {
  payload = "required"
}

func validPayload(p string) bool {
    switch p {
    case "", "optional", "required", "forbidden":
        return true
    default:
        return false
    }
}
// call before submitting: if !validPayload(job.ParameterizedJob.Payload) { ... }

if err := job.ParameterizedJob.Validate(); err != nil {
    // correct payload value and resubmit
}

When it happens

Trigger: Submitting a parameterized (dispatch) job where the payload policy field is set to a string other than "optional", "required", or "forbidden" — e.g. "maybe", "Optional" (wrong case), or a leftover value from a custom template.

Common situations: Hand-editing parameterized job templates; guessing valid values instead of consulting docs; case-sensitivity mistakes; copying configs between systems with different vocabularies.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• not a valid task schedule state
• numa affinity must be one of none, prefer, or require
• Invalid change mode. Must be one of the following: noop, sig
• job can't be submitted with a payload, only dispatched
• network address family must be one of: "", %q, %q

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