hashicorp/nomad · error

invalid configuration: unknown scheduler %q in enabled sched

Error message

invalid configuration: unknown scheduler %q in enabled schedulers

What it means

When setting up scheduling workers, Nomad validates that every entry in enabled_schedulers is a known built-in scheduler type (after skipping the internal 'core' type). An unrecognized string means the config names a scheduler that doesn't exist in this Nomad version or contains a typo, and the server refuses to start scheduling workers.

Source

Thrown at nomad/server.go:1962

// setupWorkersLocked directly manipulates the server.config, so it is not safe to
// call concurrently. Use setupWorkers() or call this with server.workerLock set.
func (s *Server) setupWorkersLocked(ctx context.Context, poolArgs SchedulerWorkerPoolArgs) error {
	// Check if all the schedulers are disabled
	if len(poolArgs.EnabledSchedulers) == 0 || poolArgs.NumSchedulers == 0 {
		s.logger.Warn("no enabled schedulers")
		return nil
	}

	// Check if the core scheduler is not enabled
	foundCore := false
	for _, sched := range poolArgs.EnabledSchedulers {
		if sched == structs.JobTypeCore {
			foundCore = true
			continue
		}

		if _, ok := scheduler.BuiltinSchedulers[sched]; !ok {
			return fmt.Errorf("invalid configuration: unknown scheduler %q in enabled schedulers", sched)
		}
	}
	if !foundCore {
		return fmt.Errorf("invalid configuration: %q scheduler not enabled", structs.JobTypeCore)
	}

	s.logger.Info("starting scheduling worker(s)", "num_workers", poolArgs.NumSchedulers, "schedulers", poolArgs.EnabledSchedulers)
	// Start the workers

	for i := 0; i < s.config.NumSchedulers; i++ {
		if w, err := NewWorker(ctx, s, poolArgs); err != nil {
			return err
		} else {
			s.logger.Debug("started scheduling worker", "id", w.ID(), "index", i+1, "of", s.config.NumSchedulers)
			s.workerShutdownGroup.AddCh(w.ShutdownCh())
			s.workers = append(s.workers, w)
		}
	}

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Fix the typo or remove the unknown entry from enabled_schedulers (valid OSS values: service, batch, system, sysbatch)
2. Run nomad agent -config-check / nomad config validate to catch this before restart
3. Check nomad version and its supported scheduler types; remove enterprise-only names from an OSS deployment
4. If you intended all schedulers, remove enabled_schedulers entirely to use the default set

Example fix

// before
enabled_schedulers = ["service", "batch", "sytem"]
// after
enabled_schedulers = ["service", "batch", "system"]

// Validate scheduler names against the built-in set before writing config
const builtin = new Set(['service', 'batch', 'system', 'sysbatch']);
const enabled = ['service', 'batch', 'system']; // from your config template
const unknown = enabled.filter(s => !builtin.has(s));
if (unknown.length) throw new Error('unknown schedulers: ' + unknown.join(', '));

try {
  startNomadServer();
} catch (e) {
  if (String(e).includes('unknown scheduler')) {
    const bad = /unknown scheduler "([^"]+)"/.exec(String(e))?.[1];
    rewriteConfigRemovingScheduler(bad);
    startNomadServer();
  } else throw e;
}

When it happens

Trigger: server.stanza enabled_schedulers contains a value not in scheduler.BuiltinSchedulers — typo (e.g. "sytem"), scheduler removed in a newer Nomad, or a custom/enterprise scheduler name used in OSS Nomad.

Common situations: Hand-edited or generated config with misspelled scheduler names (service, batch, system, sysbatch are valid); copying config from docs of a different Nomad version; enabling enterprise-only schedulers on OSS.

Related errors

• invalid configuration: %q scheduler not enabled
• Job registration, dispatch, and scale are disabled by the sc
• client setup failed: %v
• timeout cannot be negative
• Failed to start workers: %v

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