hashicorp/nomad · error

System jobs may not have a spread block

Error message

System jobs may not have a spread block

What it means

Job.Validate() rejects system jobs that declare spread blocks: 'System jobs may not have a spread block'. Spread distributes allocations across attributes of candidate nodes, which has no effect for system jobs that run on every eligible node.

Source

Thrown at nomad/structs/structs.go:4800

			mErr.Errors = append(mErr.Errors, outer)
		}
	}
	if j.Type == JobTypeSystem {
		if j.Affinities != nil {
			mErr.Errors = append(mErr.Errors, fmt.Errorf("System jobs may not have an affinity block"))
		}
	} else {
		for idx, affinity := range j.Affinities {
			if err := affinity.Validate(); err != nil {
				outer := fmt.Errorf("Affinity %d validation failed: %s", idx+1, err)
				mErr.Errors = append(mErr.Errors, outer)
			}
		}
	}

	if j.Type == JobTypeSystem {
		if j.Spreads != nil {
			mErr.Errors = append(mErr.Errors, fmt.Errorf("System jobs may not have a spread block"))
		}
	} else {
		for idx, spread := range j.Spreads {
			if err := spread.Validate(); err != nil {
				outer := fmt.Errorf("Spread %d validation failed: %s", idx+1, err)
				mErr.Errors = append(mErr.Errors, outer)
			}
		}
	}

	const MaxDescriptionCharacters = 1000
	if j.UI != nil {
		if len(j.UI.Description) > MaxDescriptionCharacters {
			mErr.Errors = append(mErr.Errors, fmt.Errorf("UI description must be under 1000 characters, currently %d", len(j.UI.Description)))
		}
	}

	if j.VersionTag != nil {

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Remove the spread block from the system job spec
2. If distribution is needed, restrict node eligibility with constraint blocks instead
3. Run 'nomad job validate' to confirm

Example fix

// before
job "sys" {
  type = "system"
  group "g" {
    spread {
      attribute = "${node.datacenter}"
    }
  }
}
// after
job "sys" {
  type = "system"
  group "g" {}
}

if job.Type == "system" && len(job.Spreads) > 0 {
    return errors.New("system jobs may not declare spread blocks")
}
return nil

if err := job.Validate(); err != nil {
    if strings.Contains(err.Error(), "spread block") {
        return ErrSystemJobSpread
    }
    return err
}

When it happens

Trigger: Registering or validating a job with type = "system" while j.Spreads is non-nil, i.e. a spread block exists in the job or group spec.

Common situations: Converting a service job to system type without deleting spread blocks, templating jobs that include spread by default, or an HCL refactor that left spread in place.

Related errors

• System jobs may not have an affinity block
• Spread %d validation failed: %s
• Job task group %s has count %d. Count cannot exceed 1 with s
• ErrConnectRequireOneNetwork
• ErrConnectInvalidNetworkMode

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