{"record":{"id":"6603a813613bba5b","repo":"hashicorp/nomad","slug":"no-cluster-leader","errorCode":null,"errorMessage":"No cluster leader","messagePattern":"No cluster leader","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"nomad/structs/errors.go","lineNumber":53,"sourceCode":"\tErrUnknownJobPrefix        = \"Unknown job\"\n\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","sourceCodeStart":35,"sourceCodeEnd":71,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/nomad/structs/errors.go#L35-L71","documentation":"ErrNoLeader is a sentinel error (nomad/structs/errors.go:53) returned by Nomad servers when an RPC requiring Raft consensus cannot find or reach the cluster leader. Without a leader the server cannot forward requests or serve writes/consistent reads, so it reports this error to clients and internal retry logic, which treats it as transient and retryable.","triggerScenarios":"Any RPC handled while no Raft leader is elected: leader election in progress after server start/restart, quorum loss (too few voting servers up), network partitions between servers, or during leader failover. Returned by RPC forwarding helpers (forwardFor, canRetry) and heartbeat/registration paths (client.go:1943).","commonSituations":"Rolling Nomad server restarts; a server cluster down to one of three nodes; firewall/network issues breaking Raft RPC between servers; freshly bootstrapped cluster not yet elected a leader; clients registering during a failover window.","solutions":["Check `nomad server members` and `nomad operator raft list-peers`; ensure a majority of voting servers are running and connected","Verify Raft ports (4647) and network connectivity between all servers; inspect server logs for leader election messages","If quorum is permanently lost, recover the cluster with `nomad operator raft peer remove` or restore from backup/snapshot, then restart clients so they re-register (clients retry automatically)","Simply wait/retry — clients already retry registration and CSI hooks treat this error as retryable"],"exampleFix":"// handling in client code: treat as transient and retry\nif strings.Contains(err.Error(), structs.ErrNoLeader.Error()) {\n    return true // retryable: wait for leader election\n}","handlingStrategy":"retry","validationCode":null,"typeGuard":"func isNoLeaderErr(err error) bool {\n    return strings.Contains(err.Error(), structs.ErrNoLeader.Error())\n}","tryCatchPattern":"for attempt := 0; attempt < 5; attempt++ {\n    if err := rpcCall(); err == nil {\n        break\n    } else if isNoLeaderErr(err) {\n        time.Sleep(backoff(attempt)) // transient: wait for leader election\n        continue\n    } else {\n        return err\n    }\n}","preventionTips":["Monitor cluster quorum and leader health with `nomad operator raft list-peers` and alerts on no-leader state","Run an odd number (3 or 5) of voting servers spread across failure domains","Verify Raft connectivity (port 4647) between servers; test after network/firewall changes","Rely on client-side retries — Nomad clients already back off and re-register when ErrNoLeader occurs"],"tags":["nomad","raft","consensus","leader-election","cluster"],"backgroundTag":"no-cluster-leader","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"}