{"record":{"id":"e35521cffe617522","repo":"hashicorp/nomad","slug":"node-does-not-support-rpc-requires-0-8-or-later","errorCode":null,"errorMessage":"Node does not support RPC; requires 0.8 or later","messagePattern":"Node does not support RPC; requires 0\\.8 or later","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"nomad/structs/errors.go","lineNumber":64,"sourceCode":"\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.\n\t// Keep the two in sync.\n\tErrResultPaginatorCreation = errors.New(errResultPaginatorCreation)\n\n\tErrUnknownNode = errors.New(ErrUnknownNodePrefix)\n\n\tErrDeploymentTerminalNoCancel    = errors.New(errDeploymentTerminalNoCancel)\n\tErrDeploymentTerminalNoFail      = errors.New(errDeploymentTerminalNoFail)\n\tErrDeploymentTerminalNoPause     = errors.New(errDeploymentTerminalNoPause)\n\tErrDeploymentTerminalNoPromote   = errors.New(errDeploymentTerminalNoPromote)\n\tErrDeploymentTerminalNoResume    = errors.New(errDeploymentTerminalNoResume)","sourceCodeStart":46,"sourceCodeEnd":82,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/nomad/structs/errors.go#L46-L82","documentation":"ErrNodeLacksRpc is returned when an RPC that requires client-side RPC support is routed to a Nomad node running a version older than 0.8, which cannot serve those endpoints. The server detects the node's advertised version is too old and refuses instead of failing with an opaque timeout or method-not-found.","triggerScenarios":"Calling ClientAllocations.GarbageCollectAll, GarbageCollect, ClientFS.Stat/Logs, or ClientStats.Stats against a node whose NomadVersion is below 0.8; forwarding any node-RPC to a pre-0.8 client agent.","commonSituations":"Mixed-version clusters during upgrades where old clients remain registered; targeting a node ID that still points at a legacy agent; automation invoking new client endpoints in a cluster with downlevel nodes.","solutions":["Upgrade the target Nomad client agent to 0.8 or later.","Target a different, up-to-date node for the RPC.","If the node is decommissioned/stale, purge its registration so requests stop routing to it.","Gate client-RPC calls on the node's reported NomadVersion in your automation."],"exampleFix":"// before\nerr := client.RPC(\"ClientAllocations.GarbageCollect\", req, &resp) // node < 0.8\n// after\nif semver.Compare(node.NomadVersion, \"0.8.0\") >= 0 {\n    err = client.RPC(\"ClientAllocations.GarbageCollect\", req, &resp)\n}","handlingStrategy":"validation","validationCode":"if semverMajorMinor(node.NomadVersion) < [2]int{0, 8} { return fmt.Errorf(\"node %s runs %s; RPC requires >= 0.8\", node.ID, node.NomadVersion) }","typeGuard":"func nodeSupportsRpc(version string) bool { v, err := semver.NewVersion(version); return err == nil && !v.LessThan(semver.MustParse(\"0.8.0\")) }","tryCatchPattern":"if err := msgpackrpc.CallWithCodec(codec, \"ClientAllocations.GarbageCollect\", req, &resp); err != nil {\n    if structs.IsErrNodeLacksRpc(err) {\n        return fmt.Errorf(\"skipping node %s: upgrade to >=0.8 required\", req.NodeID)\n    }\n    return err\n}","preventionTips":["Keep cluster clients at or above the minimum supported version before deploying features using client RPCs","Check node version via nomad node status before targeting client endpoints","During rolling upgrades, route RPCs only to upgraded nodes","Alert on downlevel agents registered in the cluster"],"tags":["rpc","nomad","versioning","compatibility"],"backgroundTag":"node-version-too-old","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"}