hashicorp/nomad · error

controller validate volume: %v

Error message

controller validate volume: %v

What it means

ClientCSI.ControllerValidateVolume forwards a CSI ControllerValidateVolume RPC to the CSI controller plugin via sendCSIControllerRPC, and wraps any forwarding failure as "controller validate volume: <err>". Validation is invoked before volume claims are created, so this error surfaces during volume registration or job placement when the controller cannot validate the volume.

Source

Thrown at nomad/client_csi_endpoint.go:56

		"ClientCSI.ControllerAttachVolume",
		structs.RateMetricWrite,
		args, reply)
	if err != nil {
		return fmt.Errorf("controller attach volume: %v", err)
	}
	return nil
}

func (a *ClientCSI) ControllerValidateVolume(args *cstructs.ClientCSIControllerValidateVolumeRequest, reply *cstructs.ClientCSIControllerValidateVolumeResponse) error {
	defer metrics.MeasureSince([]string{"nomad", "client_csi_controller", "validate_volume"}, time.Now())

	err := a.sendCSIControllerRPC(args.PluginID,
		"CSI.ControllerValidateVolume",
		"ClientCSI.ControllerValidateVolume",
		structs.RateMetricWrite,
		args, reply)
	if err != nil {
		return fmt.Errorf("controller validate volume: %v", err)
	}
	return nil
}

func (a *ClientCSI) ControllerDetachVolume(args *cstructs.ClientCSIControllerDetachVolumeRequest, reply *cstructs.ClientCSIControllerDetachVolumeResponse) error {
	defer metrics.MeasureSince([]string{"nomad", "client_csi_controller", "detach_volume"}, time.Now())

	err := a.sendCSIControllerRPC(args.PluginID,
		"CSI.ControllerDetachVolume",
		"ClientCSI.ControllerDetachVolume",
		structs.RateMetricWrite,
		args, reply)
	if err != nil {
		return fmt.Errorf("controller detach volume: %v", err)
	}
	return nil
}

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Run `nomad volume status <vol-id>` and compare the volume's requested capabilities with the plugin's advertised ones.
2. Confirm the controller plugin is running/healthy (`nomad plugin status`) and re-register the volume after fixing plugin_id.
3. Inspect plugin alloc logs for the plugin-side validation error and adjust the volume spec capabilities.

Example fix

// before
capability { access_mode = "multi-node-multi-writer"
  attachment_mode = "file-system" }
// after
# match modes the controller plugin actually supports
capability { access_mode = "single-node-writer"
  attachment_mode = "file-system" }

const plugin = await nomad.plugin(pluginID)
if (!plugin.controllers?.some(c => c.healthy)) {
  throw new Error(`controller ${pluginID} down; volume validation would fail`)
}
// also compare requested capabilities against advertised ones
const advertised = new Set(plugin.capabilities ?? [])
for (const cap of volume.requestedCapabilities) {
  if (!advertised.has(cap)) throw new Error(`capability ${cap} not supported by plugin`)
}

try { await validateVolume(spec) }
catch (e) {
  if (String(e).startsWith('controller validate volume')) {
    log.warn('CSI validation failed:', e); return { valid: false, reason: e }
  }
  throw e
}

When it happens

Trigger: `nomad volume register`/volume claim path when the controller plugin is unavailable, the plugin returns an error from ControllerValidateVolumeCapabilities, or the RPC to the plugin fails.

Common situations: Volume spec's requested capabilities don't match what the plugin advertises and the plugin returns an error; controller plugin down; plugin_id mismatch in the volume spec; CSI plugin implements validation incorrectly.

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