hashicorp/nomad · error

cannot change attachment mode of claimed volume

Error message

cannot change attachment mode of claimed volume

What it means

During CSI volume claim validation, Nomad rejects a new claim that would change the volume's attachment mode while it is already claimed. Once a volume is claimed with a specific attachment mode (e.g. file-system vs block), later claims must use the same mode to keep the volume's presentation consistent.

Source

Thrown at nomad/structs/csi.go:604

// Claim updates the allocations and changes the volume state
func (v *CSIVolume) Claim(claim *CSIVolumeClaim, alloc *Allocation) error {
	// COMPAT: volumes registered prior to 1.1.0 will be missing caps for the
	// volume on any claim. Correct this when we make the first change to a
	// claim by setting its currently claimed capability as the only requested
	// capability
	if len(v.RequestedCapabilities) == 0 && v.AccessMode != "" && v.AttachmentMode != "" {
		v.RequestedCapabilities = []*CSIVolumeCapability{
			{
				AccessMode:     v.AccessMode,
				AttachmentMode: v.AttachmentMode,
			},
		}
	}
	if v.AttachmentMode != CSIVolumeAttachmentModeUnknown &&
		claim.AttachmentMode != CSIVolumeAttachmentModeUnknown &&
		v.AttachmentMode != claim.AttachmentMode {
		return fmt.Errorf("cannot change attachment mode of claimed volume")
	}

	if claim.State == CSIVolumeClaimStateTaken {
		switch claim.Mode {
		case CSIVolumeClaimRead:
			return v.claimRead(claim, alloc)
		case CSIVolumeClaimWrite:
			return v.claimWrite(claim, alloc)
		}
	}
	// either GC or a Unpublish checkpoint
	return v.claimRelease(claim)
}

// claimRead marks an allocation as using a volume read-only
func (v *CSIVolume) claimRead(claim *CSIVolumeClaim, alloc *Allocation) error {
	if _, ok := v.ReadAllocs[claim.AllocationID]; ok {
		return nil

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Match the new claim's attachment_mode to the mode already recorded on the volume (check with `nomad volume status <id>`).
2. If the mode genuinely must change, release all claims (destroy/withdraw the volume claims) and re-claim with the new mode.
3. Create a separate CSI volume with the desired attachment mode instead of reusing the claimed one.

Example fix

// before (volume already claimed as FILESYSTEM)
volume "data" {
  type            = "csi"
  attachment_mode = "csi-volume-attachment-mode-block-device"
}
// after
volume "data" {
  type            = "csi"
  attachment_mode = "csi-volume-attachment-mode-filesystem"
}

// before submitting a job claiming a CSI volume
vol, _ := client.CSIVolumes().Info(ctx, volID)
for _, c := range vol.RequestedCapabilities { /* compare */ }
if vol.AttachmentMode != "csi-volume-attachment-mode-unknown" && vol.AttachmentMode != desiredMode {
  return fmt.Errorf("volume %s is claimed with attachment mode %s; use that mode", volID, vol.AttachmentMode)
}

_, err := client.CSIVolumes().Deregister(...) // or job register
if err != nil && strings.Contains(err.Error(), "cannot change attachment mode") {
  // inspect current claim mode with `nomad volume status` and align job spec, then retry
}

When it happens

Trigger: Submitting a job/task group volume that claims an existing CSI volume with an attachment_mode different from the mode recorded on the volume's current claim (both modes known and unequal), e.g. first claim used CSI_VOLUME_MODE_FILESYSTEM and the new one uses CSI_VOLUME_MODE_BLOCK.

Common situations: Reusing a database volume previously claimed as block-device in a job requesting filesystem mode; changing attachment_mode in a job spec after the volume was already in use; template reuse across jobs with conflicting modes.

Related errors

• volume not found: %s
• CSI.ControllerAttachVolume: VolumeID is required
• CSI.ControllerAttachVolume: ClientCSINodeID is required
• CSI.ControllerDetachVolume: VolumeID is required
• CSI.ControllerDetachVolume: ClientCSINodeID is required

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