{"record":{"id":"9c7ba9a2015fbfda","repo":"hashicorp/nomad","slug":"unable-to-determine-nomad-version","errorCode":null,"errorMessage":"Unable to determine Nomad version","messagePattern":"Unable to determine Nomad version","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"nomad/structs/errors.go","lineNumber":63,"sourceCode":"\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.\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)","sourceCodeStart":45,"sourceCodeEnd":81,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/nomad/structs/errors.go#L45-L81","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Let the node re-heartbeat/re-register so its NomadVersion is populated, then retry the RPC.","Trigger a node update (or restart the Nomad client agent) to refresh its registration.","Purge the stale node registration (nomad node status / node purge) and let it rejoin.","If you control the client, upgrade it to a version that reports NomadVersion (0.8+)."],"exampleFix":"// before\n// node registered with empty NomadVersion -> server errors\n// after\n// restart client agent so it re-registers with NomadVersion set (e.g. \"1.7.0\")","handlingStrategy":"retry","validationCode":"if node.NomadVersion == \"\" { return errors.New(\"node has not reported its Nomad version; refresh registration before RPC\") }","typeGuard":"func nodeVersionKnown(n *api.Node) bool { return n != nil && n.Version != \"\" }","tryCatchPattern":"if err := msgpackrpc.CallWithCodec(codec, \"ClientAllocations.Stats\", req, &resp); err != nil {\n    if structs.IsErrUnknownNomadVersion(err) {\n        // wait for node heartbeat, then retry once\n        time.Sleep(heartbeatGrace)\n        err = msgpackrpc.CallWithCodec(codec, \"ClientAllocations.Stats\", req, &resp)\n    }\n    return err\n}","preventionTips":["Monitor node heartbeats and alert on registrations missing version info","Restart/purge stale agents so they re-register with current version metadata","Check nomad node status Version column before routing client RPCs"],"tags":["rpc","nomad","versioning"],"backgroundTag":"unknown-node-version","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"}