hashicorp/nomad · error

alloc %q failed to claim volume %q: %w

Error message

alloc %q failed to claim volume %q: %w

What it means

During CSIVolumeClaim the store calls volume.Claim(claim, alloc) to record the new claim on the *structs.CSIVolume. If the volume rejects the claim — because it has no free capacity for the requested access mode (e.g. single-writer already claimed, or write capacity exhausted) — the store wraps that rejection in this error and aborts the transaction. The RPC caller (nomad client/node CSI plugin) surfaces it as a failed claim RPC.

Source

Thrown at nomad/state/state_store.go:2914

		}
	}

	volume, err := s.csiVolumeDenormalizePluginsTxn(txn, orig.Copy())
	if err != nil {
		return err
	}
	volume, err = s.csiVolumeDenormalizeTxn(txn, nil, volume)
	if err != nil {
		return err
	}

	// In the case of a job deregistration, there will be no allocation ID
	// for the claim but we still want to write an updated index to the volume
	// so that volume reaping is triggered
	if claim.AllocationID != "" {
		err = volume.Claim(claim, alloc)
		if err != nil {
			return fmt.Errorf("alloc %q failed to claim volume %q: %w", claim.AllocationID, volume.ID, err)
		}
	}

	volume.ModifyIndex = index
	volume.ModifyTime = now

	// Allocations are copy on write, so we want to keep the Allocation ID
	// but we need to clear the pointer so that we don't store it when we
	// write the volume to the state store. We'll get it from the db in
	// denormalize.
	for allocID := range volume.ReadAllocs {
		volume.ReadAllocs[allocID] = nil
	}
	for allocID := range volume.WriteAllocs {
		volume.WriteAllocs[allocID] = nil
	}

	if err = txn.Insert(TableCSIVolumes, volume); err != nil {

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Check `nomad volume status <id>` for existing claims and the volume's access mode
2. Use multi-node-reader-only or a separate volume if concurrent access is required
3. Increase the volume's capacity (CSI controller expand volume) or set explicit volume_capacity_min in the volume spec
4. Fix the job's volume capability requests to match what the volume supports

Example fix

# before: job requests write access to an already-claimed volume
volume "db" { type = "csi" ... }
# after: change access mode to match usage
volume "db" {
  type = "csi"
  access_mode     = "multi-node-multi-writer"
  attachment_mode = "file-system"
}

// Before scheduling, check the volume has free claims and compatible mode
vol, _, err := client.CSIVolumes().Get(volumeID, nil)
if err != nil { return err }
if vol.AccessMode == "single-node-writer" && len(vol.WriteAllocs) > 0 {
	return fmt.Errorf("volume %s already has a writer claim", volumeID)
}

func volumeClaimable(v *api.CSIVolume, wantWrite bool) bool {
	if v == nil { return false }
	if wantWrite && v.AccessMode == "single-node-writer" && len(v.WriteAllocs) > 0 { return false }
	return true
}

if err := claimVolume(volID, allocID); err != nil && strings.Contains(err.Error(), "failed to claim volume") {
	// reschedule elsewhere or use a different volume
}

When it happens

Trigger: An allocation claiming a CSI volume via Node.Batch/CSIVolumeClaim RPC when: the volume already has a writer claim (SingleNodeWriter mode), WriteAllocs is at the volume's capacity per its requested capabilities, the claim's access mode/attachment mode is incompatible, or the alloc is unknown where required.

Common situations: Two jobs scheduling against the same single-node-writer volume; volume registered with smaller capacity than the job's declared demand; misconfigured access_mode (e.g. multi-node-single-writer vs single-node-writer) in the volume spec.

Related errors

• allocation missing: %s
• storage provider does not have enough space for this snapsho
• error parsing: root should be an object
• missing policy name
• cannot specify Accessor ID

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