Spread target percentage for value %q must be between 0 and

Error message

Spread target percentage for value %q must be between 0 and 100

What it means

Spread.Validate() requires each SpreadTarget's Percent to be at most 100. If any individual target percentage exceeds 100, the job is rejected with 'Spread target percentage for value %q must be between 0 and 100'. (Values below 0 are caught earlier by int min checks/field validation.)

Source

Thrown at nomad/structs/structs.go:10343

	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))
		}
		sumPercent += uint32(target.Percent)
	}
	if sumPercent > 100 {
		mErr.Errors = append(mErr.Errors, fmt.Errorf("Sum of spread target percentages must not be greater than 100%%; got %d%%", sumPercent))
	}
	return mErr.ErrorOrNil()
}

// SpreadTarget is used to specify desired percentages for each attribute value
type SpreadTarget struct {
	// Value is a single attribute value, like "dc1"
	Value string

	// Percent is the desired percentage of allocs
	Percent uint8

	// Memoized string representation

View on GitHub (pinned to 482b49bf1a)

Solutions

Set each target percent to a value in [0, 100].
Normalize computed percentages so no single target exceeds 100.
Verify the sum of all targets is also <= 100 (a separate check).

Example fix

// before
spread {
  attribute = "${node.datacenter}"
  target "dc1" { percent = 150 }
}
// after
spread {
  attribute = "${node.datacenter}"
  target "dc1" { percent = 100 }
}

Defensive patterns

Strategy: validation

Validate before calling

if t.Percent > 100 { return fmt.Errorf("target %q percent %d exceeds 100", t.Value, t.Percent) }

Prevention

Bound each target percent to [0,100] in generators
Do not confuse percent with affinity weight scales
Check total sum separately before submission

When it happens

Trigger: Submitting a job with a spread target whose percent is > 100, e.g. target "dc1" { percent = 150 }, via HCL or the /v1/jobs API.

Common situations: Confusing percent with weight (weights go to 100 per affinity but sums differ), scripts computing percentages incorrectly, or unit mix-ups (per-mille vs percent).

Related errors

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