hashicorp/nomad · error

missing VolumeCapabilities

Error message

missing VolumeCapabilities

What it means

NodePublishVolumeRequest.Validate requires at least one VolumeCapability describing how the volume will be used (mount vs block access, filesystem type, access mode). A nil VolumeCapability means the plugin cannot determine how to expose the volume, so the request is rejected before contacting the storage provider.

Source

Thrown at plugins/csi/plugin.go:187

		TargetPath:        r.TargetPath,
		VolumeCapability:  r.VolumeCapability.ToCSIRepresentation(),
		Readonly:          r.Readonly,
		Secrets:           r.Secrets,
		VolumeContext:     r.VolumeContext,
	}
}

func (r *NodePublishVolumeRequest) Validate() error {
	if r.ExternalID == "" {
		return errors.New("missing volume ID")
	}

	if r.TargetPath == "" {
		return errors.New("missing TargetPath")
	}

	if r.VolumeCapability == nil {
		return errors.New("missing VolumeCapabilities")
	}

	return nil
}

type NodeStageVolumeRequest struct {
	// The external ID of the volume to stage.
	ExternalID string

	// If the volume was attached via a call to `ControllerPublishVolume` then
	// we need to provide the returned PublishContext here.
	PublishContext map[string]string

	// The path to which the volume MAY be staged. It MUST be an
	// absolute path in the root filesystem of the process serving this
	// request, and MUST be a directory. The CO SHALL ensure that there
	// is only one `staging_target_path` per volume. The CO SHALL ensure
	// that the path is directory and that the process serving the

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Re-register the volume with explicit attachment_mode and access_mode, e.g. `nomad volume register` with attachment_mode = "file-system", access_mode = "single-node-writer"
2. Verify the storage provider actually supports the requested capability (`nomad plugin status <csi-plugin>`)
3. Upgrade Nomad client/plugin to a compatible version if capability metadata is being dropped
4. When building requests in Go, populate VolumeCapability (mount with fs type, access mode) before Validate

Example fix

// before (HCL volume spec)
capabilities {
  # attachment_mode / access_mode omitted
}

// after (HCL volume spec)
capabilities {
  attachment_mode = "file-system"
  access_mode     = "single-node-writer"
}

if req.VolumeCapability == nil {
    return fmt.Errorf("VolumeCapability is required")
}

if err := req.Validate(); err != nil {
    if strings.Contains(err.Error(), "missing VolumeCapabilities") {
        return fmt.Errorf("volume lacks attachment_mode/access_mode: %w", err)
    }
    return err
}

When it happens

Trigger: A CSI NodePublishVolume call with r.VolumeCapability == nil — e.g. a volume registered without access_mode/capabilities, or a request constructed programmatically without a capability, or a controller failing to copy capabilities from the stage phase into the publish phase.

Common situations: Volume spec in `nomad volume register` missing `access_mode` or `attachment_mode`; provider capabilities (from ControllerGetCapabilities) not supported/propagated; hand-written Go requests omitting VolumeCapability; Nomad/plugin version skew losing capability metadata.

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

• CSI.ControllerAttachVolume: VolumeID is required
• CSI.ControllerAttachVolume: ClientCSINodeID is required
• CSI.ControllerDetachVolume: VolumeID is required
• CSI.ControllerDetachVolume: ClientCSINodeID is required
• CSI.NodeDetachVolume: PluginID is required

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