hashicorp/nomad · error

unknown volume access mode: %v

Error message

unknown volume access mode: %v

What it means

Same transformation path as the attachment-mode check: the volume's access_mode string did not match any known CSIXVolumeAccessMode constant (e.g. single-node-writer, multi-node-reader). Nomad re-validates during conversion to the plugin's VolumeCapability to defend against dev bugs, corrupted state, or incompatible Nomad versions.

Source

Thrown at plugins/csi/plugin.go:983

	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
		// nomad versions in the future.
		return nil, fmt.Errorf("unknown volume access mode: %v", sAccessMode)
	}

	return &VolumeCapability{
		AccessType:  accessType,
		AccessMode:  accessMode,
		MountVolume: sMountOptions,
	}, nil
}

func (c *VolumeCapability) ToCSIRepresentation() *csipbv1.VolumeCapability {
	if c == nil {
		return nil
	}

	vc := &csipbv1.VolumeCapability{
		AccessMode: &csipbv1.VolumeCapability_AccessMode{
			Mode: c.AccessMode.ToCSIRepresentation(),
		},

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Fix access_mode in the volume spec to a supported value (e.g. single-node-writer, single-node-reader-only, multi-node-single-writer, multi-node-multi-writer, multi-node-reader-only) and re-register
2. Run `nomad volume validate` on the HCL before registering to catch the bad value early
3. Check Nomad version compatibility if the volume was created by another binary/version and recreate the volume from a clean spec

Example fix

// before
access_mode = "multi-node-reader"
// after
access_mode = "multi-node-reader-only"

// Go: whitelist known access modes before conversion
allowed := map[string]bool{
    "single-node-reader-only": true,
    "single-node-writer": true,
    "multi-node-reader-only": true,
    "multi-node-single-writer": true,
    "multi-node-multi-writer": true,
}
if !allowed[sAccessMode] {
    return fmt.Errorf("unsupported access_mode %q", sAccessMode)
}

When it happens

Trigger: CSIVolumeCapability.AccessMode holds an unrecognized string when converting capabilities for the CSI plugin — anything not in the supported single-node-* / multi-node-* set.

Common situations: Typo'd access_mode in a hand-written volume HCL that bypassed validation; state written by a different Nomad version; corrupted server state.

Related errors

• unknown volume attachment mode: %s
• 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/d1fcc08509f3c50b. Report an issue: GitHub.