hashicorp/nomad · error

invalid access mode: %q

Error message

invalid access mode: %q

What it means

HostVolume capability validation ensures AccessMode is one of the supported single-node modes: single-node-reader, single-node-writer, single-node-single-writer, or single-node-multi-writer. Any other value returns this error.

Source

Thrown at nomad/structs/host_volumes.go:335

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)
	}

	return nil
}

// HostVolumeAttachmentModes choose the type of storage API that will be used to
// interact with the device.
const (
	HostVolumeAttachmentModeUnknown     VolumeAttachmentMode = ""
	HostVolumeAttachmentModeBlockDevice VolumeAttachmentMode = "block-device"
	HostVolumeAttachmentModeFilesystem  VolumeAttachmentMode = "file-system"
)

// HostVolumeAccessModes indicate how Nomad should make the volume available to
// concurrent allocations.
const (
	HostVolumeAccessModeUnknown VolumeAccessMode = ""

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Set access_mode to one of: single-node-reader, single-node-writer, single-node-single-writer, single-node-multi-writer
2. If multi-node access is required, use a CSI volume instead of a host volume
3. Run nomad volume validate to confirm the spec

Example fix

// before
capability { attachment_mode = "filesystem" access_mode = "multi-node-multi-writer" }
// after
capability { attachment_mode = "filesystem" access_mode = "single-node-writer" }

validAccess := map[string]bool{
  "single-node-reader": true, "single-node-writer": true,
  "single-node-single-writer": true, "single-node-multi-writer": true}
if !validAccess[cap.AccessMode] {
  return fmt.Errorf("bad access_mode %q", cap.AccessMode)
}

func validAccessMode(m string) bool {
  switch m {
  case "single-node-reader", "single-node-writer",
    "single-node-single-writer", "single-node-multi-writer":
    return true
  }
  return false
}

When it happens

Trigger: Registering or validating a host volume whose Capabilities entry has an AccessMode outside the four HostVolumeAccessModeSingleNode* constants.

Common situations: Using CSI multi-node access modes (e.g. multi-node-multi-writer) on a host volume; typo like 'single-node-reader-writer'.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• cannot register volume: node ID is required
• cannot register volume: host path is required
• missing name
• validate called on nil host volume capability
• 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/08a11160307ecf3f. Report an issue: GitHub.