{"record":{"id":"3acfa1793ebcc305","repo":"hashicorp/nomad","slug":"claiming-volumes-w","errorCode":null,"errorMessage":"claiming volumes: %w","messagePattern":"claiming volumes: %w","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"client/allocrunner/csi_hook.go","lineNumber":131,"sourceCode":"\t// Initially, populate the result map with all of the requests\n\tfor alias, volumeRequest := range tg.Volumes {\n\t\tif volumeRequest.Type == structs.VolumeTypeCSI {\n\t\t\tc.volumeResults[alias] = &volumePublishResult{\n\t\t\t\trequest: volumeRequest,\n\t\t\t\tstub: &state.CSIVolumeStub{\n\t\t\t\t\tVolumeID: volumeRequest.VolumeID(c.alloc.Name)},\n\t\t\t}\n\t\t}\n\t}\n\n\terr := c.restoreMounts(c.volumeResults)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"restoring mounts: %w\", err)\n\t}\n\n\terr = c.claimVolumes(c.volumeResults)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"claiming volumes: %w\", err)\n\t}\n\n\terr = c.mountVolumes(c.volumeResults)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"mounting volumes: %w\", err)\n\t}\n\n\t// make the mounts available to the taskrunner's volume_hook\n\tmounts := helper.ConvertMap(c.volumeResults,\n\t\tfunc(result *volumePublishResult) *csimanager.MountInfo {\n\t\t\treturn result.stub.MountInfo\n\t\t})\n\tc.hookResources.SetCSIMounts(mounts)\n\n\t// persist the published mount info so we can restore on client restarts\n\tstubs := helper.ConvertMap(c.volumeResults,\n\t\tfunc(result *volumePublishResult) *state.CSIVolumeStub {\n\t\t\treturn result.stub","sourceCodeStart":113,"sourceCodeEnd":149,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/client/allocrunner/csi_hook.go#L113-L149","documentation":"After restoring mounts, the CSI hook's Prerun claims each requested volume via claimVolumes so the allocation holds a claim on the CSI volume. This error wraps failures in acquiring those claims, e.g. the volume doesn't exist, access mode conflicts, or the controller rejects the claim.","triggerScenarios":"csiHook.Prerun() -> c.claimVolumes(c.volumeResults) returns an error: volume not found/registered, incompatible volume access mode/capabilities with the task's request, or RPC error to the CSI controller plugin.","commonSituations":"Job references a volume that was deregistered; host_volume/CSI volume requested with capabilities (access mode, fs type, mount flags) the plugin doesn't support; claim count exceeded for a single-node-reader/writer volume; CSI plugin down.","solutions":["Run nomad volume status <volume> to confirm the volume exists and check its claims/capabilities","Align the job's volume block (access_mode, attachment_mode, mount_flags) with the plugin's declared capabilities","Free conflicting claims (stop other allocs or nomad volume detach) for single-writer volumes","Ensure the CSI controller plugin is running and reachable, then reschedule the job"],"exampleFix":"// before\nvolume \"data\" { type = \"csi\" ... access_mode = \"single-node-writer\" }  # already claimed elsewhere\n// after\n$ nomad volume detach data <other-node>\n# or change job:\naccess_mode = \"multi-node-multi-writer\"  # if plugin supports it","handlingStrategy":"validation","validationCode":"const vol = await nomad.get(`volume/csi/${volumeName}`);\nconst caps = vol.RequestedCapabilities ?? [];\nif (!caps.some(c => c.AccessMode === 'single-node-writer'))\n  throw new Error(`volume ${volumeName} lacks required access mode`);\nif (vol.Claims && vol.Claims.length >= 1 && mode === 'single-node-writer')\n  throw new Error('volume already claimed; free the claim first');","typeGuard":null,"tryCatchPattern":"try {\n  await runJob(job);\n} catch (err) {\n  if (String(err).includes('claiming volumes')) {\n    const claims = await nomad.get(`volume/csi/${volumeName}`);\n    for (const c of claims.Claims ?? []) await nomad.volumeDetach(volumeName, c.NodeID);\n    await runJob(job); // retry once after clearing claims\n  } else throw err;\n}","preventionTips":["Match job volume access_mode/attachment_mode to the plugin's supported capabilities","Detach stale claims before rescheduling single-writer volumes","Verify volume registration (nomad volume register) before submitting jobs","Keep CSI controller reachable so claim RPCs succeed"],"tags":["csi","storage","volumes","nomad"],"backgroundTag":"csi-volume-claim-failed","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"}