hashicorp/nomad · error

Missing spread attribute

Error message

Missing spread attribute

What it means

Spread.Validate() appends this error when the spread stanza's Attribute field is empty. Spread scheduling needs an attribute (node class, datacenter, meta key, etc.) to distribute allocations across its possible values; without it the spread cannot be evaluated and validation fails.

Source

Thrown at nomad/structs/structs.go:10326

	ns := new(Spread)
	*ns = *s

	ns.SpreadTarget = CopySliceSpreadTarget(s.SpreadTarget)
	return ns
}

func (s *Spread) String() string {
	if s.str != "" {
		return s.str
	}
	s.str = fmt.Sprintf("%s %s %v", s.Attribute, s.SpreadTarget, s.Weight)
	return s.str
}

func (s *Spread) Validate() error {
	var mErr multierror.Error
	if s.Attribute == "" {
		mErr.Errors = append(mErr.Errors, errors.New("Missing spread attribute"))
	}
	if s.Weight <= 0 || s.Weight > 100 {
		mErr.Errors = append(mErr.Errors, errors.New("Spread block must have a positive weight from 0 to 100"))
	}
	seen := make(map[string]struct{})
	sumPercent := uint32(0)

	for _, target := range s.SpreadTarget {
		// Make sure there are no duplicates
		_, ok := seen[target.Value]
		if !ok {
			seen[target.Value] = struct{}{}
		} else {
			mErr.Errors = append(mErr.Errors, fmt.Errorf("Spread target value %q already defined", target.Value))
		}
		if target.Percent > 100 {
			mErr.Errors = append(mErr.Errors, fmt.Errorf("Spread target percentage for value %q must be between 0 and 100", target.Value))
		}

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Add an attribute to the spread stanza, e.g. spread { attribute = "${node.datacenter}" ... }.
2. If you want the referenced even-spread behavior, pick the node property you care about (${node.class}, ${meta.*}).
3. Remove the spread stanza if it was unintentional.
4. Run `nomad job validate` before submitting.

Example fix

// before
spread {
  weight = 50
}
// after
spread {
  attribute = "${node.datacenter}"
  weight    = 50
}

func validateSpread(s *structs.Spread) error {
	if s.Attribute == "" {
		return fmt.Errorf("spread stanza requires an attribute")
	}
	if s.Weight <= 0 || s.Weight > 100 {
		return fmt.Errorf("spread weight must be 1-100, got %d", s.Weight)
	}
	return nil
}

func isSpreadable(s *structs.Spread) bool { return s != nil && s.Attribute != "" && s.Weight > 0 && s.Weight <= 100 }

When it happens

Trigger: Submitting a job/group spread stanza with weight and/or spread targets but no attribute, or constructing Spread{Weight: 50, SpreadTarget: ...} in Go leaving Attribute "" before Validate.

Common situations: Users copying spread examples that rely on even distribution and thinking attribute is optional; templated job generation that omits the attribute when only targets are customized; JSON API submissions missing the "attribute" key.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• Spread block must have a positive weight from 0 to 100
• Missing job datacenters
• Job datacenter must be non-empty string
• must specify cron block
• Spread target value %q already defined

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