hashicorp/nomad · error

validate called on nil host volume capability

Error message

validate called on nil host volume capability

What it means

HostVolumeCapability.Validate is a value-receiver method, so it can be invoked on a nil *HostVolumeCapability. To fail safely rather than panic, it returns the sentinel 'validate called on nil host volume capability' when hvc == nil. It then validates the AttachmentMode enum.

Source

Thrown at nomad/structs/host_volumes.go:319

// HostVolumeCapability is the requested attachment and access mode for a volume
type HostVolumeCapability struct {
	AttachmentMode VolumeAttachmentMode
	AccessMode     VolumeAccessMode
}

func (hvc *HostVolumeCapability) Copy() *HostVolumeCapability {
	if hvc == nil {
		return nil
	}

	nhvc := *hvc
	return &nhvc
}

func (hvc *HostVolumeCapability) Validate() error {
	if hvc == nil {
		return errors.New("validate called on nil host volume capability")
	}

	switch hvc.AttachmentMode {
	case HostVolumeAttachmentModeBlockDevice,
		HostVolumeAttachmentModeFilesystem:
	default:
		return fmt.Errorf("invalid attachment mode: %q", hvc.AttachmentMode)
	}

	switch hvc.AccessMode {
	case HostVolumeAccessModeSingleNodeReader,
		HostVolumeAccessModeSingleNodeWriter,
		HostVolumeAccessModeSingleNodeSingleWriter,
		HostVolumeAccessModeSingleNodeMultiWriter:
	default:
		return fmt.Errorf("invalid access mode: %q", hvc.AccessMode)
	}

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Initialize HostVolumeCapability before validation (non-nil pointer with a valid AttachmentMode)
2. Set attachment_mode to a valid value (block_device or filesystem) once non-nil
3. Guard call sites with a nil check before invoking Validate
4. If capabilities are optional, skip validating nil entries instead of passing them through

Example fix

// before
var cap *structs.HostVolumeCapability
cap.Validate() // returns nil-capability error

// after
cap := &structs.HostVolumeCapability{
  AttachmentMode: structs.HostVolumeAttachmentModeFilesystem,
}
if err := cap.Validate(); err != nil { /* handle */ }

if hvc == nil {
	return errors.New("capability must be non-nil")
}
switch hvc.AttachmentMode {
case "block_device", "filesystem":
default:
	return fmt.Errorf("invalid attachment mode %q", hvc.AttachmentMode)
}

func validHostVolumeCapability(hvc *structs.HostVolumeCapability) bool {
	return hvc != nil &&
		(hvc.AttachmentMode == structs.HostVolumeAttachmentModeBlockDevice ||
		 hvc.AttachmentMode == structs.HostVolumeAttachmentModeFilesystem)
}

When it happens

Trigger: Calling Validate() on a nil *HostVolumeCapability pointer, e.g. a HostVolume whose Capabilities list or field was left nil, routed through validateVolumeUpdate or tests.

Common situations: Constructing HostVolume structs programmatically without initializing capabilities; JSON payloads omitting the capabilities field resulting in nil pointers; tests probing nil-safety of Validate.

Related errors

• cannot register volume: node ID is required
• cannot register volume: host path is required
• missing name
• missing node for client registration
• invalid constraint %s: host volumes of the same name are alw

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