hashicorp/nomad · error

expand is not implemented by this controller plugin

Error message

expand is not implemented by this controller plugin

What it means

During controller-driven volume expansion, expandVolume only expands when the requested minimum capacity exceeds the volume's current capacity AND the CSI controller plugin advertises CSIControllerSupportsExpand. If the plugin lacks that capability, this error is returned because the controller cannot perform the resize.

Source

Thrown at nomad/csi_endpoint.go:1349

		if newMax < vol.Capacity {
			return fmt.Errorf("max requested capacity (%s) less than or equal to current (%s)",
				humanize.Bytes(uint64(newMax)),
				humanize.Bytes(uint64(vol.Capacity)))
		}
	}

	// Values are validated, so go ahead and update vol to commit to state,
	// even if the external volume does not need expanding.
	vol.RequestedCapacityMin = newMin
	vol.RequestedCapacityMax = newMax

	// Only expand if new min is greater than current capacity.
	if newMin <= vol.Capacity {
		return nil
	}

	if !plugin.HasControllerCapability(structs.CSIControllerSupportsExpand) {
		return errors.New("expand is not implemented by this controller plugin")
	}

	capability, err := csi.VolumeCapabilityFromStructs(vol.AttachmentMode, vol.AccessMode, vol.MountOptions)
	if err != nil {
		logger.Debug("unable to get capability from volume", "error", err)
		// We'll optimistically send a nil capability, as an "unknown"
		// attachment mode (likely not attached) is acceptable per the spec.
	}

	method := "ClientCSI.ControllerExpandVolume"
	cReq := &cstructs.ClientCSIControllerExpandVolumeRequest{
		ExternalVolumeID: vol.ExternalID,
		Secrets:          vol.Secrets,
		CapacityRange:    capacity,
		VolumeCapability: capability,
	}
	cReq.PluginID = plugin.ID
	cResp := &cstructs.ClientCSIControllerExpandVolumeResponse{}

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Check plugin capabilities: 'nomad plugin status <plugin>' and confirm EXPAND controller capability is listed
2. Expand the volume externally via the storage vendor's own tooling, then re-register/update the volume capacity in Nomad
3. Upgrade or switch to a CSI plugin/driver version that supports controller expansion
4. If newMin <= current capacity, no expansion is attempted — verify the requested size actually exceeds vol.Capacity

Example fix

// before
nomad volume scale ebs-vol min-capacity=100GiB  // plugin lacks expand
// after: expand via vendor CLI then update Nomad record
aws ec2 modify-volume --volume-id vol-xxx --size 100
nomad volume update ebs-vol.hcl

// shell: confirm the plugin supports expansion before scaling
nomad plugin status <pluginID> -json | jq -e '.ControllersSupportedFunctions // .ControllerInfo.SupportedFunctions | has("EXPAND_VOLUME")' \
  || { echo 'plugin cannot expand volumes'; exit 1; }

// Go client
if _, err := client.CSI().VolumeScale(volID, newMin, newMax); err != nil {
    if strings.Contains(err.Error(), "expand is not implemented") {
        return expandExternally(volID, newMin) // vendor CLI path
    }
    return err
}

When it happens

Trigger: Submitting a volume-scale request ('nomad volume scale' or volume update via API) for a CSI volume whose controller plugin does not declare the EXPAND_VOLUME controller capability, while newMin > vol.Capacity.

Common situations: Using a storage driver whose controller does not support online/offline expansion (common with some CSI drivers); attempting to grow a volume after deploying a plugin that only supports attach/detach; scaling a volume in a job file without checking plugin capabilities.

Related errors

• CSI.ControllerAttachVolume: VolumeID is required
• CSI.ControllerAttachVolume: ClientCSINodeID is required
• CSI.ControllerDetachVolume: VolumeID is required
• CSI.ControllerDetachVolume: ClientCSINodeID is required
• CSI.NodeDetachVolume: PluginID is required

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