hashicorp/nomad · error

Unknown payload requirement

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.

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"
}
Defensive patterns

Strategy: validation

Validate before calling

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

Try / catch

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

Prevention

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


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

Appendix: 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)