job_default_priority cannot be %d. Must be between %d and %d

Error message

job_default_priority cannot be %d. Must be between %d and %d

What it means

The default job priority must lie within [structs.JobDefaultPriority, jobMaxPriority) — it must not exceed the configured max and must be at least the built-in default (80? structs.JobDefaultPriority). convertServerConfig validates it after resolving job_max_priority.

Source

Thrown at command/agent/agent.go:371

			conf.AutopilotConfig.DisableUpgradeMigration = *agentConfig.Autopilot.DisableUpgradeMigration
		}
		if agentConfig.Autopilot.EnableCustomUpgrades != nil {
			conf.AutopilotConfig.EnableCustomUpgrades = *agentConfig.Autopilot.EnableCustomUpgrades
		}
	}

	jobMaxPriority := structs.JobDefaultMaxPriority
	if agentConfig.Server.JobMaxPriority != nil && *agentConfig.Server.JobMaxPriority != 0 {
		jobMaxPriority = *agentConfig.Server.JobMaxPriority
		if jobMaxPriority < structs.JobDefaultMaxPriority || jobMaxPriority > structs.JobMaxPriority {
			return nil, fmt.Errorf("job_max_priority cannot be %d. Must be between %d and %d", *agentConfig.Server.JobMaxPriority, structs.JobDefaultMaxPriority, structs.JobMaxPriority)
		}
	}
	jobDefaultPriority := structs.JobDefaultPriority
	if agentConfig.Server.JobDefaultPriority != nil && *agentConfig.Server.JobDefaultPriority != 0 {
		jobDefaultPriority = *agentConfig.Server.JobDefaultPriority
		if jobDefaultPriority < structs.JobDefaultPriority || jobDefaultPriority >= jobMaxPriority {
			return nil, fmt.Errorf("job_default_priority cannot be %d. Must be between %d and %d", *agentConfig.Server.JobDefaultPriority, structs.JobDefaultPriority, jobMaxPriority)
		}
	}
	conf.JobMaxPriority = jobMaxPriority
	conf.JobDefaultPriority = jobDefaultPriority

	jobMaxCount := structs.JobDefaultMaxCount
	if agentConfig.Server.JobMaxCount != nil {
		jobMaxCount = *agentConfig.Server.JobMaxCount
		if jobMaxCount < 0 {
			return nil, fmt.Errorf("job_max_count (%d) cannot be negative", jobMaxCount)
		}
	}
	conf.JobMaxCount = jobMaxCount

	if agentConfig.Server.JobTrackedVersions != nil {
		if *agentConfig.Server.JobTrackedVersions <= 0 {
			return nil, fmt.Errorf("job_tracked_versions must be greater than 0")
		}

View on GitHub (pinned to 482b49bf1a)

Solutions

Set job_default_priority so that structs.JobDefaultPriority <= N < job_max_priority (e.g. default 80 with max 100).
If raising the default, also raise job_max_priority above it.
Omit the option to use the built-in default priority.

Example fix

// before
server {
  job_max_priority     = 100
  job_default_priority = 100
}
// after
server {
  job_max_priority     = 100
  job_default_priority = 80
}

Defensive patterns

Strategy: validation

Validate before calling

// Go: pre-validate default < max
maxP := structs.JobDefaultMaxPriority
if p := cfg.Server.JobMaxPriority; p != nil && *p != 0 { maxP = *p }
if d := cfg.Server.JobDefaultPriority; d != nil && *d != 0 &&
   (*d < structs.JobDefaultPriority || *d >= maxP) {
    return fmt.Errorf("job_default_priority %d outside [%d,%d)", *d, structs.JobDefaultPriority, maxP)
}

Try / catch

conf, err := convertServerConfig(agentCfg)
if err != nil {
    if strings.Contains(err.Error(), "job_default_priority cannot be") {
        return fmt.Errorf("job_default_priority must be >= default and < job_max_priority: %w", err)
    }
    return err
}

Prevention

Always review job_default_priority together with job_max_priority.
Keep the default strictly below the max (e.g. 80 vs 100).
Omit the option to use structs.JobDefaultPriority.

When it happens

Trigger: Setting server { job_default_priority = N } where N != 0 and (N < structs.JobDefaultPriority or N >= the effective jobMaxPriority), during agent start or reload.

Common situations: Setting default priority equal to or above max priority; lowering max below the existing default via a separate job_max_priority override; templating generating defaults >= caps.

Related errors

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