hashicorp/nomad · error

unknown volume attachment mode: %s

Error message

unknown volume attachment mode: %s

What it means

When transforming a Nomad CSIVolume's requested capabilities into the CSI plugin's VolumeCapability, the attachment (access) type string was not 'mount' or 'block'. Nomad validates this at job submission, so hitting it here indicates corrupted state, a development bug, or a Nomad version mismatch writing incompatible data.

Source

Thrown at plugins/csi/plugin.go:963

	AccessMode VolumeAccessMode

	// Indicate that the volume will be accessed via the filesystem API.
	MountVolume *structs.CSIMountOptions
}

func VolumeCapabilityFromStructs(sAccessType structs.VolumeAttachmentMode, sAccessMode structs.VolumeAccessMode, sMountOptions *structs.CSIMountOptions) (*VolumeCapability, error) {
	var accessType VolumeAccessType
	switch sAccessType {
	case structs.CSIVolumeAttachmentModeBlockDevice:
		accessType = VolumeAccessTypeBlock
	case structs.CSIVolumeAttachmentModeFilesystem:
		accessType = VolumeAccessTypeMount
	default:
		// These fields are validated during job submission, but here we perform a
		// final check during transformation into the requisite CSI Data type to
		// defend against development bugs and corrupted state - and incompatible
		// nomad versions in the future.
		return nil, fmt.Errorf("unknown volume attachment mode: %s", sAccessType)
	}

	var accessMode VolumeAccessMode
	switch sAccessMode {
	case structs.CSIVolumeAccessModeSingleNodeReader:
		accessMode = VolumeAccessModeSingleNodeReaderOnly
	case structs.CSIVolumeAccessModeSingleNodeWriter:
		accessMode = VolumeAccessModeSingleNodeWriter
	case structs.CSIVolumeAccessModeMultiNodeMultiWriter:
		accessMode = VolumeAccessModeMultiNodeMultiWriter
	case structs.CSIVolumeAccessModeMultiNodeSingleWriter:
		accessMode = VolumeAccessModeMultiNodeSingleWriter
	case structs.CSIVolumeAccessModeMultiNodeReader:
		accessMode = VolumeAccessModeMultiNodeReaderOnly
	default:
		// These fields are validated during job submission, but here we perform a
		// final check during transformation into the requisite CSI Data type to
		// defend against development bugs and corrupted state - and incompatible

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Correct the volume specification so attachment_mode is exactly "mount" or "block", then re-register: `nomad volume register <corrected.hcl>`
2. Validate the job/volume spec with `nomad job validate` / `nomad volume validate` before submission
3. If state corruption is suspected, check the Nomad server state store and Nomad version compatibility; upgrade Nomad and re-create the volume

Example fix

// before (volume hcl)
attachment_mode = " Mount"
// after
attachment_mode = "mount"
// or "block" for raw block volumes

// Go: assert attachment mode before building capabilities
valid := map[string]bool{"mount": true, "block": true}
if !valid[sAccessType] {
    return fmt.Errorf("attachment_mode must be 'mount' or 'block', got %q", sAccessType)
}

When it happens

Trigger: CSIVolumeCapability.AccessType contains a value other than "mount" or "block" when the volume capability is converted for the plugin (volume publish/claim path).

Common situations: Hand-edited or corrupted volume state in the state store; an older/newer Nomad binary reading volumes written by an incompatible version; a bug in custom tooling writing volume specs directly.

Related errors

• unknown volume access mode: %v
• CSI.ControllerValidateVolume: VolumeID is required
• volume clone ID cannot be updated
• volume requested capabilities update was not compatible with
• missing secret ID

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