What causes "numa affinity must be one of none, prefer, or require" in hashicorp/nomad?

Set numa.affinity to exactly one of none, prefer, or require

numa affinity must be one of none, prefer, or require

Error message

numa affinity must be one of none, prefer, or require

What it means

The NUMA affinity field in a job's NUMA resource stanza only accepts the enumerated values 'none', 'prefer', or 'require'. Validate returns this error when Affinity holds any other string. It is a strict enum check to catch typos before scheduling.

Source

Thrown at nomad/structs/numa.go:87

func (n *NUMA) Copy() *NUMA {
	if n == nil {
		return nil
	}
	return &NUMA{
		Affinity: n.Affinity,
		Devices:  slices.Clone(n.Devices),
	}
}

func (n *NUMA) Validate() error {
	if n == nil {
		return nil
	}
	switch n.Affinity {
	case NoneNUMA, PreferNUMA, RequireNUMA:
		return nil
	default:
		return errors.New("numa affinity must be one of none, prefer, or require")
	}
}

// Requested returns true if the NUMA.Affinity is set to one of "prefer" or
// "require" and will require such CPU cores for scheduling.
func (n *NUMA) Requested() bool {
	if n == nil || n.Affinity == NoneNUMA {
		return false
	}
	return true
}

// LegacyNodeCpuResources is the pre-1.7 CPU resources struct. It remains here
// for compatibility and can be removed in Nomad 1.9+.
//
// Deprecated; use NodeProcessorResources instead.
type LegacyNodeCpuResources struct {
	// Deprecated; do not use this value except for compatibility.

View on GitHub (pinned to 482b49bf1a)

Solutions

Set numa.affinity to exactly one of none, prefer, or require
Remove the affinity field entirely (defaults to none)
Validate the job with nomad job validate before submitting

Example fix

// before
numa {
  affinity = "required"
}
// after
numa {
  affinity = "require"
}

Defensive patterns

Strategy: validation

Validate before calling

var validNUMA = map[string]bool{"none": true, "prefer": true, "require": true}
if numa != nil && numa.Affinity != "" && !validNUMA[numa.Affinity] {
    return fmt.Errorf("numa affinity %q invalid; must be none, prefer, or require", numa.Affinity)
}

Type guard

func validNUMAAffinity(a string) bool {
    switch a { case "", "none", "prefer", "require": return true }
    return false
}

Prevention

Use only documented enum literals in job HCL
Run nomad job validate in CI before submitting jobs
Avoid hand-transcribing option names from other systems

When it happens

Trigger: Submitting a job whose resources.cpu.numa.affinity stanza contains a value other than none/prefer/require (e.g. 'required', 'preferred', 'best-effort').

Common situations: Typos in job HCL; guessing value names instead of using the documented enum; configs carried over from other orchestrators with different NUMA option naming.

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/d57e93d12d61b85b. Report an issue: GitHub.