hashicorp/nomad · error

cannot register volume: host path is required

Error message

cannot register volume: host path is required

What it means

Validation in the host volume Register RPC: a volume registration omits HostPath. Static host volumes registered via the API must point at an existing absolute path on the target node; an empty path would mount nothing.

Source

Thrown at nomad/host_volume_endpoint.go:354

		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)
	}

	warn, err := v.enforceEnterprisePolicy(

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Provide host_path (HostPath) with an absolute path existing on the target node
2. Check templating/variable interpolation so the path is not empty at submit time
3. Validate client-side before the RPC that both node_id and host_path are non-empty
4. Ensure the path exists on the node and is permitted by the client's host volume enabled/denylist config

Example fix

// before
job 'data' { host_volume "data" { } }
// after
host_volume "data" {
  path = "/opt/data"
}

// shell
[ -n "$HOST_PATH" ] || { echo 'host path required'; exit 1; }
nomad node status "$NODE_ID" >/dev/null 2>&1
[ -d "$HOST_PATH" ] || { echo "path $HOST_PATH missing on node"; exit 1; }

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

When it happens

Trigger: Registering a host volume via the API/CLI with the HostPath field omitted or set to ""; templated volume manifests where the path variable failed to interpolate.

Common situations: Copied CSI volume specs (which have no host path) reused for host volumes; config generation tools emitting empty host_path; manual JSON crafted against /v1/volumes/host/register.

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: node ID 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/f984daa9267c7c3f. Report an issue: GitHub.