dequeue disallowed: calling scheduler version is %d; leader

Error message

dequeue disallowed: calling scheduler version is %d; leader version is %d

What it means

Fires in Eval.Dequeue when the calling server's scheduler version is older than the leader's: the leader refuses to hand evaluations to a server that may schedule them with outdated semantics.

Source

Thrown at nomad/eval_endpoint.go:141

	aclObj, err := e.srv.AuthenticateServerOnly(e.ctx, args)
	e.srv.MeasureRPCRate("eval", structs.RateMetricWrite, args)
	if err != nil || !aclObj.AllowServerOp() {
		return structs.ErrPermissionDenied
	}

	if done, err := e.srv.forward("Eval.Dequeue", args, args, reply); done {
		return err
	}
	defer metrics.MeasureSince([]string{"nomad", "eval", "dequeue"}, time.Now())

	// Ensure there is at least one scheduler
	if len(args.Schedulers) == 0 {
		return fmt.Errorf("dequeue requires at least one scheduler type")
	}

	// Check that there isn't a scheduler version mismatch
	if args.SchedulerVersion != scheduler.SchedulerVersion {
		return fmt.Errorf("dequeue disallowed: calling scheduler version is %d; leader version is %d",
			args.SchedulerVersion, scheduler.SchedulerVersion)
	}

	// Ensure there is a default timeout
	if args.Timeout <= 0 {
		args.Timeout = DefaultDequeueTimeout
	}

	// If the eval broker is paused, attempt to block and wait for a state
	// change before returning. This avoids a tight loop and mimics the
	// behaviour where there are no evals to process.
	//
	// The call can return because either the timeout is reached or the broker
	// SetEnabled function was called to modify its state. It is possible this
	// is because of leadership transition, therefore the RPC should exit to
	// allow all safety checks and RPC forwarding to occur again.
	//
	// The log line is trace, because the default worker timeout is 500ms which

View on GitHub (pinned to 482b49bf1a)

Solutions

Upgrade the lagging server to at least the leader's Nomad version
Wait for the upgraded leader to hand off or for the old leader to step down

Defensive patterns

Strategy: validation

When it happens

Trigger: Thrown at nomad/eval_endpoint.go:141 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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