hashicorp/nomad · error

volume requested capabilities update was not compatible with

Error message

volume requested capabilities update was not compatible with existing capability in use

What it means

Raised by CSIVolume.Merge (nomad/structs/csi.go:823) when the volume already has an AccessMode/AttachmentMode in use and the submitted RequestedCapabilities no longer include a capability matching the existing access/attachment mode pair. CSI volumes cannot change the mode a volume is currently mounted with; new requested capabilities are only accepted if at least one is compatible with the capability in use.

Source

Thrown at nomad/structs/csi.go:823

		errs = multierror.Append(errs, errors.New(
			"volume snapshot ID cannot be updated"))
	}

	// must be compatible with volume_capabilities
	if v.AccessMode != CSIVolumeAccessModeUnknown ||
		v.AttachmentMode != CSIVolumeAttachmentModeUnknown {
		var ok bool
		for _, cap := range other.RequestedCapabilities {
			if cap.AccessMode == v.AccessMode &&
				cap.AttachmentMode == v.AttachmentMode {
				ok = true
				break
			}
		}
		if ok {
			v.RequestedCapabilities = other.RequestedCapabilities
		} else {
			errs = multierror.Append(errs, errors.New(
				"volume requested capabilities update was not compatible with existing capability in use"))
		}
	} else {
		v.RequestedCapabilities = other.RequestedCapabilities
	}

	// topologies are immutable, so topology request changes must be
	// compatible with the existing topology, if any
	if len(v.Topologies) > 0 {
		if !v.RequestedTopologies.Equal(other.RequestedTopologies) {
			errs = multierror.Append(errs, errors.New(
				"volume topology request update was not compatible with existing topology"))
		}
	}

	// MountOptions can be updated so long as the volume isn't in use
	if v.InUse() {
		if !v.MountOptions.Equal(other.MountOptions) {

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Add a requested capability whose access/attachment mode pair matches the one currently in use, alongside any new capabilities
2. Stop all allocations using the volume so it is no longer in use, then update capabilities
3. Deregister and re-register the volume with the desired capabilities if a mode change is genuinely required

Example fix

// before
requested_capabilities {
  access_mode     = "multi-node-multi-writer" # incompatible with in-use single-node-writer
  attachment_mode = "file-system"
}
// after
requested_capabilities {
  access_mode     = "single-node-writer" # keeps compatibility with in-use mode
  attachment_mode = "file-system"
}

// ensure at least one requested capability matches the in-use pair
func compatibleCaps(existing, update *structs.CSIVolume) bool {
    if existing.AccessMode == structs.CSIVolumeAccessModeUnknown &&
        existing.AttachmentMode == structs.CSIVolumeAttachmentModeUnknown {
        return true
    }
    for _, cap := range update.RequestedCapabilities {
        if cap.AccessMode == existing.AccessMode && cap.AttachmentMode == existing.AttachmentMode {
            return true
        }
    }
    return false
}

func hasCapability(v *structs.CSIVolume, am structs.CSIVolumeAccessMode, at structs.CSIVolumeAttachmentMode) bool {
    for _, c := range v.RequestedCapabilities {
        if c.AccessMode == am && c.AttachmentMode == at {
            return true
        }
    }
    return false
}

When it happens

Trigger: Updating a volume (nomad volume update / VolumeUpsert) whose RequestedCapabilities list contains no entry with cap.AccessMode == v.AccessMode && cap.AttachmentMode == v.AttachmentMode, while the existing volume has non-unknown AccessMode or AttachmentMode.

Common situations: Switching a volume from single-node-writer to multi-node-reader while allocations are mounted; removing the original capability stanza from the spec and adding only new ones; changing filesystem/mount protocol capability that the in-use mount cannot support.

Related errors

• volume clone ID cannot be updated
• missing secret ID
• CSI.ControllerValidateVolume: VolumeID is required
• CSI.ControllerAttachVolume: VolumeID is required
• CSI.ControllerAttachVolume: ClientCSINodeID is required

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