hashicorp/nomad · error

unknown scheduler '%s'

Error message

unknown scheduler '%s'

What it means

NewScheduler looks up the scheduler type name in the BuiltinSchedulers factory map and returns this error when the requested name is not a registered scheduler type. Nomad only supports a fixed set of scheduler names (e.g. 'service', 'batch', 'system', 'sysbatch'), so an unrecognized name means a bad scheduler type configuration.

Source

Thrown at scheduler/scheduler.go:38

// BuiltinSchedulers contains the built in registered schedulers
// which are available
var BuiltinSchedulers = map[string]structs.Factory{
	"service":  NewServiceScheduler,
	"batch":    NewBatchScheduler,
	"system":   NewSystemScheduler,
	"sysbatch": NewSysBatchScheduler,
}

// NewScheduler is used to instantiate and return a new scheduler
// given the scheduler name, initial state, and planner.
func NewScheduler(
	name string, logger log.Logger, eventsCh chan<- any, state structs.State, planner structs.Planner,
) (structs.Scheduler, error) {
	// Lookup the factory function
	factory, ok := BuiltinSchedulers[name]
	if !ok {
		return nil, fmt.Errorf("unknown scheduler '%s'", name)
	}

	// Instantiate the scheduler
	sched := factory(logger, eventsCh, state, planner)
	return sched, nil
}

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Check the scheduler name passed to NewScheduler; only 'service', 'batch', 'system', and 'sysbatch' are built in.
2. Fix the typo or invalid scheduler type in the job file or calling code.
3. Upgrade the Nomad binary if the job uses a scheduler type introduced after the running version (e.g. sysbatch needs Nomad >= 1.1).
4. If using a custom/enterprise scheduler, verify it is registered into BuiltinSchedulers at init time.

Example fix

// before
eval.Type = "batch-job"
sched, err := scheduler.NewScheduler(eval.Type, logger, eventsCh, state, planner)
// after
eval.Type = "batch" // must be one of: service, batch, system, sysbatch
sched, err := scheduler.NewScheduler(eval.Type, logger, eventsCh, state, planner)

valid := map[string]bool{"service": true, "batch": true, "system": true, "sysbatch": true}
if !valid[schedulerName] {
    return fmt.Errorf("scheduler %q is not a builtin scheduler", schedulerName)
}

func isBuiltinScheduler(name string) bool {
    _, ok := scheduler.BuiltinSchedulers[name]
    return ok
}

sched, err := scheduler.NewScheduler(name, logger, eventsCh, state, planner)
if err != nil {
    if strings.Contains(err.Error(), "unknown scheduler") {
        return fmt.Errorf("invalid scheduler type %q; allowed: service, batch, system, sysbatch", name)
    }
    return err
}

When it happens

Trigger: Calling NewScheduler (directly or via reconcileQueuedAllocations, Plan, or invokeScheduler in the leader worker loop) with a scheduler name that is not a key in BuiltinSchedulers — typically from a job with an unknown/typo'd scheduler type, or a custom scheduler name not registered.

Common situations: Typo in scheduler type; using a scheduler type from a newer Nomad version on an older binary (e.g. 'sysbatch' on pre-1.1 Nomad); third-party tooling constructing evaluations with invalid scheduler names.

Related errors

• Job registration, dispatch, and scale are disabled by the sc
• timeout cannot be negative
• failed to get scheduler configuration: %v
• failed to get scheduler configuration: %v
• no CNI network config found

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