{"record":{"id":"b6ce9fade8313ed0","repo":"hashicorp/nomad","slug":"cannot-change-attachment-mode-of-claimed-volume","errorCode":null,"errorMessage":"cannot change attachment mode of claimed volume","messagePattern":"cannot change attachment mode of claimed volume","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"nomad/structs/csi.go","lineNumber":604,"sourceCode":"\n// Claim updates the allocations and changes the volume state\nfunc (v *CSIVolume) Claim(claim *CSIVolumeClaim, alloc *Allocation) error {\n\t// COMPAT: volumes registered prior to 1.1.0 will be missing caps for the\n\t// volume on any claim. Correct this when we make the first change to a\n\t// claim by setting its currently claimed capability as the only requested\n\t// capability\n\tif len(v.RequestedCapabilities) == 0 && v.AccessMode != \"\" && v.AttachmentMode != \"\" {\n\t\tv.RequestedCapabilities = []*CSIVolumeCapability{\n\t\t\t{\n\t\t\t\tAccessMode:     v.AccessMode,\n\t\t\t\tAttachmentMode: v.AttachmentMode,\n\t\t\t},\n\t\t}\n\t}\n\tif v.AttachmentMode != CSIVolumeAttachmentModeUnknown &&\n\t\tclaim.AttachmentMode != CSIVolumeAttachmentModeUnknown &&\n\t\tv.AttachmentMode != claim.AttachmentMode {\n\t\treturn fmt.Errorf(\"cannot change attachment mode of claimed volume\")\n\t}\n\n\tif claim.State == CSIVolumeClaimStateTaken {\n\t\tswitch claim.Mode {\n\t\tcase CSIVolumeClaimRead:\n\t\t\treturn v.claimRead(claim, alloc)\n\t\tcase CSIVolumeClaimWrite:\n\t\t\treturn v.claimWrite(claim, alloc)\n\t\t}\n\t}\n\t// either GC or a Unpublish checkpoint\n\treturn v.claimRelease(claim)\n}\n\n// claimRead marks an allocation as using a volume read-only\nfunc (v *CSIVolume) claimRead(claim *CSIVolumeClaim, alloc *Allocation) error {\n\tif _, ok := v.ReadAllocs[claim.AllocationID]; ok {\n\t\treturn nil","sourceCodeStart":586,"sourceCodeEnd":622,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/nomad/structs/csi.go#L586-L622","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Match the new claim's attachment_mode to the mode already recorded on the volume (check with `nomad volume status <id>`).","If the mode genuinely must change, release all claims (destroy/withdraw the volume claims) and re-claim with the new mode.","Create a separate CSI volume with the desired attachment mode instead of reusing the claimed one."],"exampleFix":"// before (volume already claimed as FILESYSTEM)\nvolume \"data\" {\n  type            = \"csi\"\n  attachment_mode = \"csi-volume-attachment-mode-block-device\"\n}\n// after\nvolume \"data\" {\n  type            = \"csi\"\n  attachment_mode = \"csi-volume-attachment-mode-filesystem\"\n}","handlingStrategy":"validation","validationCode":"// before submitting a job claiming a CSI volume\nvol, _ := client.CSIVolumes().Info(ctx, volID)\nfor _, c := range vol.RequestedCapabilities { /* compare */ }\nif vol.AttachmentMode != \"csi-volume-attachment-mode-unknown\" && vol.AttachmentMode != desiredMode {\n  return fmt.Errorf(\"volume %s is claimed with attachment mode %s; use that mode\", volID, vol.AttachmentMode)\n}","typeGuard":null,"tryCatchPattern":"_, err := client.CSIVolumes().Deregister(...) // or job register\nif err != nil && strings.Contains(err.Error(), \"cannot change attachment mode\") {\n  // inspect current claim mode with `nomad volume status` and align job spec, then retry\n}","preventionTips":["Check `nomad volume status <id>` for the current attachment mode before claiming.","Standardize one attachment mode per volume across all consuming jobs.","When a mode change is required, plan a full claim release first.","Keep job volume templates in sync with the volume registry."],"tags":["nomad","csi","volume","claim","storage"],"backgroundTag":"volume-claim-conflict","analyzedSha":"482b49bf1aec006f089bcfc7e632d8f6ac303e5e","analyzedAt":"2026-09-04T07:54:14.808Z","contentChangedAt":"2026-09-04T07:54:14.808Z","schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}