{"record":{"id":"7855544ff0cf8c2a","repo":"hashicorp/nomad","slug":"not-ready-to-serve-consistent-reads","errorCode":null,"errorMessage":"Not ready to serve consistent reads","messagePattern":"Not ready to serve consistent reads","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"nomad/structs/errors.go","lineNumber":54,"sourceCode":"\tErrUnknownEvaluationPrefix = \"Unknown evaluation\"\n\tErrUnknownDeploymentPrefix = \"Unknown deployment\"\n\n\terrRPCCodedErrorPrefix = \"RPC Error:: \"\n\n\terrDeploymentTerminalNoCancel    = \"can't cancel terminal deployment\"\n\terrDeploymentTerminalNoFail      = \"can't fail terminal deployment\"\n\terrDeploymentTerminalNoPause     = \"can't pause terminal deployment\"\n\terrDeploymentTerminalNoPromote   = \"can't promote terminal deployment\"\n\terrDeploymentTerminalNoResume    = \"can't resume terminal deployment\"\n\terrDeploymentTerminalNoUnblock   = \"can't unblock terminal deployment\"\n\terrDeploymentTerminalNoRun       = \"can't run terminal deployment\"\n\terrDeploymentTerminalNoSetHealth = \"can't set health of allocations for a terminal deployment\"\n\terrDeploymentRunningNoUnblock    = \"can't unblock running deployment\"\n)\n\nvar (\n\tErrNoLeader                   = errors.New(errNoLeader)\n\tErrNotReadyForConsistentReads = errors.New(errNotReadyForConsistentReads)\n\tErrNoRegionPath               = errors.New(errNoRegionPath)\n\tErrTokenNotFound              = errors.New(errTokenNotFound)\n\tErrTokenExpired               = errors.New(errTokenExpired)\n\tErrTokenInvalid               = errors.New(errTokenInvalid)\n\tErrPermissionDenied           = errors.New(errPermissionDenied)\n\tErrJobRegistrationDisabled    = errors.New(errJobRegistrationDisabled)\n\tErrNoNodeConn                 = errors.New(errNoNodeConn)\n\tErrUnknownMethod              = errors.New(errUnknownMethod)\n\tErrUnknownNomadVersion        = errors.New(errUnknownNomadVersion)\n\tErrNodeLacksRpc               = errors.New(errNodeLacksRpc)\n\tErrMissingAllocID             = errors.New(errMissingAllocID)\n\tErrIncompatibleFiltering      = errors.New(errIncompatibleFiltering)\n\tErrMalformedChooseParameter   = errors.New(errMalformedChooseParameter)\n\n\t// ErrResultPaginatorCreation is returned by list RPC handlers when the\n\t// result paginator cannot be built, for example when the server cannot\n\t// evaluate a requested filter expression. api.ResultPaginatorErrorContent\n\t// duplicates its message so the CLI can match it without importing structs.","sourceCodeStart":36,"sourceCodeEnd":72,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/nomad/structs/errors.go#L36-L72","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Retry the request after a short delay — the FSM catches up and consistent reads succeed (blocking queries wait automatically when using wait/index semantics)","Use stale reads (`?stale` / stale consistency) when exact quorum consistency is not required","Check server health and Raft lag (`nomad operator raft state`/logs) if the error persists, indicating a stalled FSM"],"exampleFix":"// server-side pattern in nomad/rpc.go\nif isLeader {\n    return nil, structs.ErrNotReadyForConsistentReads // blocking query will wait/retry\n}","handlingStrategy":"retry","validationCode":null,"typeGuard":"func isNotReadyForConsistentReads(err error) bool {\n    return errors.Is(err, structs.ErrNotReadyForConsistentReads) || strings.Contains(err.Error(), structs.ErrNotReadyForConsistentReads.Error())\n}","tryCatchPattern":"resp, err := queryConsistent()\nif isNotReadyForConsistentReads(err) {\n    time.Sleep(500 * time.Millisecond)\n    resp, err = queryConsistent() // FSM catches up quickly; retry succeeds\n}","preventionTips":["Allow warm-up time after server restarts/failovers before running consistency-sensitive checks","Use stale reads when approximate data is acceptable, avoiding the error entirely","Alert on persistently high Raft apply lag, which prolongs the not-ready window"],"tags":["nomad","raft","consistency","read-repair","transient"],"backgroundTag":"not-ready-for-consistent-reads","analyzedSha":"482b49bf1aec006f089bcfc7e632d8f6ac303e5e","analyzedAt":"2026-09-04T07:54:14.808Z","contentChangedAt":"2026-09-04T07:54:14.808Z","schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}