hashicorp/nomad · error

Spread target value %q already defined

Error message

Spread target value %q already defined

What it means

Spread.Validate() checks that each Value in the spread's SpreadTarget list is unique. If the same target value appears more than once, Nomad rejects the job with 'Spread target value %q already defined'. Duplicate targets would double-count percentages and make scheduling weights ambiguous.

Source

Thrown at nomad/structs/structs.go:10340

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))
		}
		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

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Remove or merge the duplicate spread target entries so each value appears once.
2. Combine the percentages of duplicates into a single target (respecting the 100% sum limit).
3. Deduplicate values programmatically before rendering the job spec.

Example fix

// before
spread {
  attribute = "${node.datacenter}"
  target "dc1" { percent = 30 }
  target "dc1" { percent = 20 }
}
// after
spread {
  attribute = "${node.datacenter}"
  target "dc1" { percent = 50 }
}

seen := map[string]bool{}
for _, t := range spread.SpreadTarget {
  if seen[t.Value] { return fmt.Errorf("duplicate spread target %q", t.Value) }
  seen[t.Value] = true
}

When it happens

Trigger: Registering a job whose spread block lists two spread stanzas (or API SpreadTarget entries) with the same value, e.g. value = "dc1" twice, at job submission time.

Common situations: HCL with repeated spread target stanzas after copy-paste, merged/concatenated generated job specs, or templating loops that emit the same value twice.

Related errors

• Spread target percentage for value %q must be between 0 and
• Sum of spread target percentages must not be greater than 10
• Disconnect cannot be configured with both lost_after and sto
• lost_after cannot be a negative duration
• stop_after cannot be a negative duration

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