hashicorp/nomad · error

Node does not support RPC; requires 0.8 or later

Error message

Node does not support RPC; requires 0.8 or later

What it means

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.

Source

Thrown at nomad/structs/errors.go:64

	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.
	// Keep the two in sync.
	ErrResultPaginatorCreation = errors.New(errResultPaginatorCreation)

	ErrUnknownNode = errors.New(ErrUnknownNodePrefix)

	ErrDeploymentTerminalNoCancel    = errors.New(errDeploymentTerminalNoCancel)
	ErrDeploymentTerminalNoFail      = errors.New(errDeploymentTerminalNoFail)
	ErrDeploymentTerminalNoPause     = errors.New(errDeploymentTerminalNoPause)
	ErrDeploymentTerminalNoPromote   = errors.New(errDeploymentTerminalNoPromote)
	ErrDeploymentTerminalNoResume    = errors.New(errDeploymentTerminalNoResume)

View on GitHub (pinned to 482b49bf1a)

Solutions

  1. Upgrade the target Nomad client agent to 0.8 or later.
  2. Target a different, up-to-date node for the RPC.
  3. If the node is decommissioned/stale, purge its registration so requests stop routing to it.
  4. Gate client-RPC calls on the node's reported NomadVersion in your automation.

Example fix

// before
err := client.RPC("ClientAllocations.GarbageCollect", req, &resp) // node < 0.8
// after
if semver.Compare(node.NomadVersion, "0.8.0") >= 0 {
    err = client.RPC("ClientAllocations.GarbageCollect", req, &resp)
}
Defensive patterns

Strategy: validation

Validate before calling

if semverMajorMinor(node.NomadVersion) < [2]int{0, 8} { return fmt.Errorf("node %s runs %s; RPC requires >= 0.8", node.ID, node.NomadVersion) }

Type guard

func nodeSupportsRpc(version string) bool { v, err := semver.NewVersion(version); return err == nil && !v.LessThan(semver.MustParse("0.8.0")) }

Try / catch

if err := msgpackrpc.CallWithCodec(codec, "ClientAllocations.GarbageCollect", req, &resp); err != nil {
    if structs.IsErrNodeLacksRpc(err) {
        return fmt.Errorf("skipping node %s: upgrade to >=0.8 required", req.NodeID)
    }
    return err
}

Prevention

When it happens

Trigger: 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.

Common situations: 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.

Related errors

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