{"record":{"id":"0e1f24e37dea2703","repo":"hashicorp/nomad","slug":"cannot-register-volume-node-id-is-required","errorCode":null,"errorMessage":"cannot register volume: node ID is required","messagePattern":"cannot register volume: node ID is required","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"nomad/host_volume_endpoint.go","lineNumber":351,"sourceCode":"\t\tvol.Namespace = args.RequestNamespace()\n\t}\n\tif !allowVolume(aclObj, vol.Namespace) {\n\t\treturn structs.ErrPermissionDenied\n\t}\n\t// Check if override is set and we do not have permissions\n\tif args.PolicyOverride {\n\t\tif !aclObj.AllowNsOp(vol.Namespace, acl.NamespaceCapabilitySentinelOverride) {\n\t\t\treturn structs.ErrPermissionDenied\n\t\t}\n\t}\n\n\tsnap, err := v.srv.State().Snapshot()\n\tif err != nil {\n\t\treturn err\n\t}\n\n\tif vol.NodeID == \"\" {\n\t\treturn errors.New(\"cannot register volume: node ID is required\")\n\t}\n\tif vol.HostPath == \"\" {\n\t\treturn errors.New(\"cannot register volume: host path is required\")\n\t}\n\n\texisting, err := v.validateVolumeUpdate(vol, snap)\n\tif err != nil {\n\t\treturn err\n\t}\n\n\t// set zero values as needed, possibly from existing\n\tnow := time.Now()\n\tvol.CanonicalizeForRegister(existing, now)\n\n\t// make sure any nodes or pools actually exist\n\terr = v.validateVolumeForState(vol, snap)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"validating volume %q against state failed: %v\", vol.ID, err)","sourceCodeStart":333,"sourceCodeEnd":369,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/nomad/host_volume_endpoint.go#L333-L369","documentation":"The HostVolume.Register RPC validates the submitted volume before persisting it. A host volume must reference the node that provides it; when vol.NodeID is empty, registration is rejected with this validation error.","triggerScenarios":"POSTing to /v1/volumes/host/register (or 'nomad host volume create' equivalents) with a HostVolume struct lacking the NodeID field; HCL/JSON volume spec omitting node_id while using the direct register API.","commonSituations":"Automation/templates registering host volumes copied from CSI volume specs (which use a plugin ID and topology instead of NodeID); API calls that forgot node_id after upgrading Nomad versions.","solutions":["Set the node_id field in the volume registration payload to the target node's ID (from 'nomad node status')","Use 'nomad volume create' with the csi/host volume HCL including the node attribute","Validate the payload before the RPC: reject empty node_id client-side","If dynamic host volumes, ensure the creation flow passes the node through correctly"],"exampleFix":"// before\n{\n  \"Name\": \"data\",\n  \"HostPath\": \"/opt/data\"\n}\n// after\n{\n  \"Name\": \"data\",\n  \"NodeID\": \"1a2b3c4d-....\",\n  \"HostPath\": \"/opt/data\"\n}","handlingStrategy":"validation","validationCode":"// shell\n[ -n \"$NODE_ID\" ] || { echo 'node_id required for host volume registration'; exit 1; }\nnomad node status \"$NODE_ID\" >/dev/null 2>&1 || { echo 'unknown node'; exit 1; }","typeGuard":null,"tryCatchPattern":"// Go\nif vol.NodeID == \"\" || vol.HostPath == \"\" {\n    return fmt.Errorf(\"host volume requires node_id and host_path\")\n}\n_, _, err := client.HostVolumes().Register(vol, nil)","preventionTips":["Always populate node_id (from 'nomad node status') in register payloads","Don't reuse CSI volume specs as host-volume specs — required fields differ","Add client-side schema checks for required fields before RPC","Lint templated volume manifests for empty interpolations"],"tags":["nomad","host-volume","validation"],"backgroundTag":"missing-required-argument","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"}