hashicorp/nomad · error

missing volume ID

Error message

missing volume ID

What it means

NodePublishVolumeRequest.Validate in the CSI plugin layer requires the ExternalID field, which identifies the remote storage volume being mounted into a task. An empty ExternalID means Nomad's CSI client could not supply the provider's volume ID, so the request is rejected before being sent to the storage plugin. This guards against publishing a mount with no backing volume.

Source

Thrown at plugins/csi/plugin.go:179

	if r == nil {
		return nil
	}

	return &csipbv1.NodePublishVolumeRequest{
		VolumeId:          r.ExternalID,
		PublishContext:    r.PublishContext,
		StagingTargetPath: r.StagingTargetPath,
		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

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Verify the volume was successfully created/registered with `nomad volume status <id>` and has a valid ExternalID
2. Re-register the volume (`nomad volume register`) with a correct CSI volume ID from the provider
3. Check that the CSI controller plugin CreateVolume returned a non-empty volume_id
4. If writing Go against the plugin API, set ExternalID before calling Validate

Example fix

// before
req := &csi.NodePublishVolumeRequest{TargetPath: "/mnt/data"}

// after
req := &csi.NodePublishVolumeRequest{
    ExternalID:  "vol-0abc123",
    TargetPath:  "/mnt/data",
}

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

if err := req.Validate(); err != nil {
    if strings.Contains(err.Error(), "missing volume ID") {
        return fmt.Errorf("volume not registered with provider: %w", err)
    }
    return err
}

When it happens

Trigger: A CSI NodePublishVolume RPC is issued with r.ExternalID == "" — typically when a volume claim resolved to a volume with no provider-assigned ExternalID, or code constructs the request manually without setting ExternalID.

Common situations: Malformed/empty CSI volume registration in the Nomad state store; a storage provider returning a volume without an ExternalID; hand-written Go code building a NodePublishVolumeRequest for tests or custom controllers omitting the field.

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/6c97766da65ebb43. Report an issue: GitHub.