hashicorp/nomad · error

cannot register volume: node ID is required

Error message

cannot register volume: node ID is required

What it means

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.

Source

Thrown at nomad/host_volume_endpoint.go:351

		vol.Namespace = args.RequestNamespace()
	}
	if !allowVolume(aclObj, vol.Namespace) {
		return structs.ErrPermissionDenied
	}
	// Check if override is set and we do not have permissions
	if args.PolicyOverride {
		if !aclObj.AllowNsOp(vol.Namespace, acl.NamespaceCapabilitySentinelOverride) {
			return structs.ErrPermissionDenied
		}
	}

	snap, err := v.srv.State().Snapshot()
	if err != nil {
		return err
	}

	if vol.NodeID == "" {
		return errors.New("cannot register volume: node ID is required")
	}
	if vol.HostPath == "" {
		return errors.New("cannot register volume: host path is required")
	}

	existing, err := v.validateVolumeUpdate(vol, snap)
	if err != nil {
		return err
	}

	// set zero values as needed, possibly from existing
	now := time.Now()
	vol.CanonicalizeForRegister(existing, now)

	// make sure any nodes or pools actually exist
	err = v.validateVolumeForState(vol, snap)
	if err != nil {
		return fmt.Errorf("validating volume %q against state failed: %v", vol.ID, err)

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Set the node_id field in the volume registration payload to the target node's ID (from 'nomad node status')
2. Use 'nomad volume create' with the csi/host volume HCL including the node attribute
3. Validate the payload before the RPC: reject empty node_id client-side
4. If dynamic host volumes, ensure the creation flow passes the node through correctly

Example fix

// before
{
  "Name": "data",
  "HostPath": "/opt/data"
}
// after
{
  "Name": "data",
  "NodeID": "1a2b3c4d-....",
  "HostPath": "/opt/data"
}

// shell
[ -n "$NODE_ID" ] || { echo 'node_id required for host volume registration'; exit 1; }
nomad node status "$NODE_ID" >/dev/null 2>&1 || { echo 'unknown node'; exit 1; }

// Go
if vol.NodeID == "" || vol.HostPath == "" {
    return fmt.Errorf("host volume requires node_id and host_path")
}
_, _, err := client.HostVolumes().Register(vol, nil)

When it happens

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

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

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• cannot register volume: host path is required
• missing name
• validate called on nil host volume capability
• invalid constraint %s: host volumes of the same name are alw
• cannot update a volume in use: claimed by allocs (%s)

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