hashicorp/nomad · error

CSI.ControllerCreateVolume: %v

Error message

CSI.ControllerCreateVolume: %v

What it means

This error is returned by the Nomad client's CSI ControllerCreateVolume RPC handler when the client-side request fails during req.ToCSIRequest() — the conversion of Nomad's internal volume-creation request into a CSI protobuf request. It wraps the conversion error with the 'CSI.ControllerCreateVolume' prefix so server logs identify the failing controller operation.

Source

Thrown at client/csi_endpoint.go:199

	}
	return err
}

func (c *CSI) ControllerCreateVolume(req *structs.ClientCSIControllerCreateVolumeRequest, resp *structs.ClientCSIControllerCreateVolumeResponse) error {
	defer metrics.MeasureSince([]string{"client", "csi_controller", "create_volume"}, time.Now())

	plugin, err := c.findControllerPlugin(req.PluginID)
	if err != nil {
		// the server's view of the plugin health is stale, so let it know it
		// should retry with another controller instance
		return fmt.Errorf("CSI.ControllerCreateVolume: %w: %v",
			nstructs.ErrCSIClientRPCRetryable, err)
	}
	defer plugin.Close()

	csiReq, err := req.ToCSIRequest()
	if err != nil {
		return fmt.Errorf("CSI.ControllerCreateVolume: %v", err)
	}

	ctx, cancelFn := c.requestContext()
	defer cancelFn()

	// CSI ControllerCreateVolume errors for timeout, codes.Unavailable and
	// codes.ResourceExhausted are retried; all other errors are fatal.
	cresp, err := plugin.ControllerCreateVolume(ctx, csiReq,
		grpc_retry.WithPerRetryTimeout(CSIPluginRequestTimeout),
		grpc_retry.WithMax(3),
		grpc_retry.WithBackoff(grpc_retry.BackoffExponential(100*time.Millisecond)))
	if err != nil {
		return fmt.Errorf("CSI.ControllerCreateVolume: %v", err)
	}

	if cresp == nil || cresp.Volume == nil {
		c.c.logger.Warn("plugin did not return error or volume; this is a bug in the plugin and should be reported to the plugin author")
		return fmt.Errorf("CSI.ControllerCreateVolume: plugin did not return error or volume")

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Inspect the wrapped '%v' detail message to see why ToCSIRequest failed and fix the offending field in the volume registration/spec
2. Verify Nomad server and client are the same version to avoid incompatible CSI request structs
3. Check how the volume was registered (nomad volume register / CSI spec) for invalid capacity or capability values
4. If it persists on valid input, file a Nomad issue with the full error and volume spec

// Before issuing a controller create-volume RPC, validate the volume spec
// that will be converted by ToCSIRequest
if vol == nil || vol.ID == "" || vol.PluginID == "" {
    return fmt.Errorf("volume spec incomplete: id=%q pluginID=%q", vol.ID, vol.PluginID)
}
if vol.RequestedCapacityMin <= 0 {
    return fmt.Errorf("volume %q: invalid requested capacity %d", vol.ID, vol.RequestedCapacityMin)
}

When it happens

Trigger: req.ToCSIRequest() returns an error, which occurs when the incoming ClientCSIControllerCreateVolumeRequest cannot be translated into a csi.CreateVolumeRequest (e.g. invalid/nil fields in the request struct produced upstream by the Nomad server).

Common situations: Bugs or version mismatches between the Nomad server and client producing malformed controller requests; volume spec fields that fail protobuf conversion; a plugin/job registration path populating inconsistent capacity or capability fields.

Related errors

• nil response from plugin.NodeExpandVolume
• CSI plugin failed to register: %w
• failed to probe plugin: %w
• CSI.ControllerValidateVolume: %v
• CSI.ControllerAttachVolume: %v

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