hashicorp/nomad · error

Dispatch request included unpermitted metadata keys: %v

Error message

Dispatch request included unpermitted metadata keys: %v

What it means

Parameterized jobs declare meta_required and meta_optional key lists. Any metadata key supplied in the dispatch that is in neither list is 'unpermitted' and causes rejection, keeping dispatch inputs strictly bounded by the job spec.

Source

Thrown at nomad/job_endpoint.go:2174

	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)
		opt := optional.Contains(k)
		if !req && !opt {
			unpermitted[k] = struct{}{}
		}
	}

	if len(unpermitted) != 0 {
		flat := make([]string, 0, len(unpermitted))
		for k := range unpermitted {
			flat = append(flat, k)
		}

		return fmt.Errorf("Dispatch request included unpermitted metadata keys: %v", flat)
	}

	missing := make(map[string]struct{})
	for _, k := range job.ParameterizedJob.MetaRequired {
		if _, ok := req.Meta[k]; !ok {
			missing[k] = struct{}{}
		}
	}

	if len(missing) != 0 {
		flat := make([]string, 0, len(missing))
		for k := range missing {
			flat = append(flat, k)
		}

		return fmt.Errorf("Dispatch did not provide required meta keys: %v", flat)
	}

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Remove the unpermitted keys from the dispatch call
2. Add the keys to meta_optional (or meta_required) in the job's parameterized stanza and resubmit
3. Fix key-name typos so they match the declared lists

Example fix

// before (job declares meta_required=["run_id"])
nomad job dispatch batch-process run_id=7 bogus=1
// after
nomad job dispatch batch-process run_id=7

allowed := map[string]struct{}{}
for _, k := range append(job.ParameterizedJob.MetaRequired, job.ParameterizedJob.MetaOptional...) {
    allowed[k] = struct{}{}
}
for k := range meta {
    if _, ok := allowed[k]; !ok {
        return fmt.Errorf("meta key %q is not permitted for job %s", k, jobID)
    }
}

When it happens

Trigger: Dispatching with meta keys not declared in the parameterized job's meta_required/meta_optional stanzas, e.g. `nomad job dispatch job key=val` where 'key' is undeclared.

Common situations: Job spec tightened (meta lists reduced) while callers still pass old keys; typos in meta key names; shared dispatch scripts passing job-specific keys to many parameterized jobs.

Related errors

• Payload is not provided but required by parameterized job
• Payload provided but forbidden by parameterized job
• Duplicate key %q in passed metadata
• 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/072e7bea8da9f967. Report an issue: GitHub.