hashicorp/nomad · error

Unable to determine Nomad version

Error message

Unable to determine Nomad version

What it means

ErrUnknownNomadVersion is returned when a server must forward an RPC to a Nomad client but the client did not advertise its version, so the server cannot decide whether the client supports the RPC. It guards against sending modern endpoints (e.g. ClientAllocations garbage-collection) to nodes of unknown capability.

Source

Thrown at nomad/structs/errors.go:63

	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.
	// 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)

View on GitHub (pinned to 482b49bf1a)

Solutions

  1. Let the node re-heartbeat/re-register so its NomadVersion is populated, then retry the RPC.
  2. Trigger a node update (or restart the Nomad client agent) to refresh its registration.
  3. Purge the stale node registration (nomad node status / node purge) and let it rejoin.
  4. If you control the client, upgrade it to a version that reports NomadVersion (0.8+).

Example fix

// before
// node registered with empty NomadVersion -> server errors
// after
// restart client agent so it re-registers with NomadVersion set (e.g. "1.7.0")
Defensive patterns

Strategy: retry

Validate before calling

if node.NomadVersion == "" { return errors.New("node has not reported its Nomad version; refresh registration before RPC") }

Type guard

func nodeVersionKnown(n *api.Node) bool { return n != nil && n.Version != "" }

Try / catch

if err := msgpackrpc.CallWithCodec(codec, "ClientAllocations.Stats", req, &resp); err != nil {
    if structs.IsErrUnknownNomadVersion(err) {
        // wait for node heartbeat, then retry once
        time.Sleep(heartbeatGrace)
        err = msgpackrpc.CallWithCodec(codec, "ClientAllocations.Stats", req, &resp)
    }
    return err
}

Prevention

When it happens

Trigger: nodeSupportsRpc encountering a node whose NomadVersion field is empty/unset; RPCs like ClientAllocations.GarbageCollectAll/GarbageCollect/Stats routed to a node registered before version reporting existed; stale node registration lacking version metadata.

Common situations: Nodes upgraded from very old Nomad versions whose registration data is stale; agents that re-registered without a heartbeat updating version info; tests simulating pre-0.8 nodes with no version set.

Related errors

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