hashicorp/nomad · error

missing volume definition

Error message

missing volume definition

What it means

HostVolume.Create requires a volume definition embedded in the request (args.Volume). If the request specifies a target but carries no Volume object, the endpoint returns "missing volume definition". The RPC intentionally does not guess defaults; a fully-formed volume spec is mandatory.

Source

Thrown at nomad/host_volume_endpoint.go:213

	if !v.srv.peersCache.ServersMeetMinimumVersion(
		v.srv.Region(),
		minVersionDynamicHostVolumes,
		false,
	) {
		return fmt.Errorf(
			"all servers should be running version %v or later to use dynamic host volumes",
			minVersionDynamicHostVolumes,
		)
	}

	allowVolume := acl.NamespaceValidator(acl.NamespaceCapabilityHostVolumeCreate)
	aclObj, err := v.srv.ResolveACL(args)
	if err != nil {
		return err
	}

	if args.Volume == nil {
		return fmt.Errorf("missing volume definition")
	}

	vol := args.Volume
	if vol.Namespace == "" {
		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
		}
	}

	// ensure we only try to create a valid volume or make valid updates to a
	// volume

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Include a complete volume definition in the request: {"volume": {"name": "...", "host_path": "...", ...}}.
2. Check JSON key spelling and nesting when calling the HTTP API directly.
3. Prefer the official CLI/Go client (nomad host volume create) which constructs the Volume struct correctly.
4. Validate the payload against the api.HostVolume struct for your Nomad version.

Example fix

// before: missing nested object
{"name": "web-vol"}
// after
{"volume": {"name": "web-vol", "type": "host", "requested_capabilities": [{"Capability": "mount"}]}}

// validate payload before sending
if req.Volume == nil || req.Volume.Name == "" || req.Volume.HostPath == "" {
    return fmt.Errorf("request must embed a complete volume definition")
}

func hasVolumeDef(req *api.HostVolumeCreateRequest) bool {
    return req != nil && req.Volume != nil && req.Volume.Name != ""
}

err := client.HostVolumes().Create(req, nil)
if err != nil && strings.Contains(err.Error(), "missing volume definition") {
    // fix payload: nested 'volume' object required
}

When it happens

Trigger: Sending a HostVolumeCreateRequest with nil/omitted Volume field — e.g. calling the raw RPC, an API client that serializes the body without the 'volume' key, or `nomad host volume create` given flags that fail to build a volume struct.

Common situations: Custom automation hitting the HTTP API with a JSON body missing the nested volume object, typos in the JSON field name (e.g. 'volumes' instead of 'volume'), or old tooling unaware of the required nested definition.

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

• ErrPluginNotExists
• Error listing host volumes
• Missing allocation ID
• Filter expression cannot be used with other filter parameter
• task driver %q for %q does not support host volumes

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