hashicorp/nomad · warning

Not ready to serve consistent reads

Error message

Not ready to serve consistent reads

What it means

ErrNotReadyForConsistentReads is a sentinel (nomad/structs/errors.go:54) returned by blocking-query RPC handling (nomad/rpc.go:656) when a server is the leader but its Raft state machine has not yet caught up enough to serve consistent (quorum) reads — typically during leader establishment or after a snapshot restore. It is transient: once the FSM is ready, reads succeed; blocking queries wait for readiness instead of failing.

Source

Thrown at nomad/structs/errors.go:54

	ErrUnknownEvaluationPrefix = "Unknown evaluation"
	ErrUnknownDeploymentPrefix = "Unknown deployment"

	errRPCCodedErrorPrefix = "RPC Error:: "

	errDeploymentTerminalNoCancel    = "can't cancel terminal deployment"
	errDeploymentTerminalNoFail      = "can't fail terminal deployment"
	errDeploymentTerminalNoPause     = "can't pause terminal deployment"
	errDeploymentTerminalNoPromote   = "can't promote terminal deployment"
	errDeploymentTerminalNoResume    = "can't resume terminal deployment"
	errDeploymentTerminalNoUnblock   = "can't unblock terminal deployment"
	errDeploymentTerminalNoRun       = "can't run terminal deployment"
	errDeploymentTerminalNoSetHealth = "can't set health of allocations for a terminal deployment"
	errDeploymentRunningNoUnblock    = "can't unblock running deployment"
)

var (
	ErrNoLeader                   = errors.New(errNoLeader)
	ErrNotReadyForConsistentReads = errors.New(errNotReadyForConsistentReads)
	ErrNoRegionPath               = errors.New(errNoRegionPath)
	ErrTokenNotFound              = errors.New(errTokenNotFound)
	ErrTokenExpired               = errors.New(errTokenExpired)
	ErrTokenInvalid               = errors.New(errTokenInvalid)
	ErrPermissionDenied           = errors.New(errPermissionDenied)
	ErrJobRegistrationDisabled    = errors.New(errJobRegistrationDisabled)
	ErrNoNodeConn                 = errors.New(errNoNodeConn)
	ErrUnknownMethod              = errors.New(errUnknownMethod)
	ErrUnknownNomadVersion        = errors.New(errUnknownNomadVersion)
	ErrNodeLacksRpc               = errors.New(errNodeLacksRpc)
	ErrMissingAllocID             = errors.New(errMissingAllocID)
	ErrIncompatibleFiltering      = errors.New(errIncompatibleFiltering)
	ErrMalformedChooseParameter   = errors.New(errMalformedChooseParameter)

	// ErrResultPaginatorCreation is returned by list RPC handlers when the
	// result paginator cannot be built, for example when the server cannot
	// evaluate a requested filter expression. api.ResultPaginatorErrorContent
	// duplicates its message so the CLI can match it without importing structs.

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Retry the request after a short delay — the FSM catches up and consistent reads succeed (blocking queries wait automatically when using wait/index semantics)
2. Use stale reads (`?stale` / stale consistency) when exact quorum consistency is not required
3. Check server health and Raft lag (`nomad operator raft state`/logs) if the error persists, indicating a stalled FSM

Example fix

// server-side pattern in nomad/rpc.go
if isLeader {
    return nil, structs.ErrNotReadyForConsistentReads // blocking query will wait/retry
}

func isNotReadyForConsistentReads(err error) bool {
    return errors.Is(err, structs.ErrNotReadyForConsistentReads) || strings.Contains(err.Error(), structs.ErrNotReadyForConsistentReads.Error())
}

resp, err := queryConsistent()
if isNotReadyForConsistentReads(err) {
    time.Sleep(500 * time.Millisecond)
    resp, err = queryConsistent() // FSM catches up quickly; retry succeeds
}

When it happens

Trigger: A consistent-read RPC (default default-consistency read such as Job.List) arrives on the leader while the server's FSM is still applying entries (e.g. right after election or restore). Also asserted in rpc_test.go:181 via WaitForConsistentReads test helper.

Common situations: Hitting the API immediately after a server becomes leader; large Raft backlogs after downtime; snapshot restores; monitoring scripts polling the API right at a failover moment.

Related errors

• failed to reset heartbeat since server is not leader
• unsupported minimum common raft protocol version
• must provide peer id or address
• cluster ID not ready yet
• deployment promotion cannot be undone

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