hashicorp/nomad · error

invalid attachment mode: %q

Error message

invalid attachment mode: %q

What it means

HostVolume capability validation ensures AttachmentMode is one of the supported values: block-device or filesystem. Any other string fails with this error, preventing invalid storage API selections from reaching nodes.

Source

Thrown at nomad/structs/host_volumes.go:326

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

	return nil
}

// HostVolumeAttachmentModes choose the type of storage API that will be used to
// interact with the device.
const (
	HostVolumeAttachmentModeUnknown     VolumeAttachmentMode = ""

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Set attachment_mode to exactly "block-device" or "filesystem"
2. Check 'nomad volume validate' or docs for accepted values
3. Fix client-side templating generating the mode string

Example fix

// before
capability { attachment_mode = "block" access_mode = "single-node-writer" }
// after
capability { attachment_mode = "block-device" access_mode = "single-node-writer" }

validModes := map[string]bool{"block-device": true, "filesystem": true}
if !validModes[cap.AttachmentMode] {
  return fmt.Errorf("bad attachment_mode %q", cap.AttachmentMode)
}

func validAttachmentMode(m string) bool {
  return m == "block-device" || m == "filesystem"
}

When it happens

Trigger: Registering or validating a host volume (HostVolume.Validate / validateVolumeUpdate) whose Capabilities entry has an AttachmentMode not in {HostVolumeAttachmentModeBlockDevice, HostVolumeAttachmentModeFilesystem}.

Common situations: Typo in HCL (e.g. attachment_mode = "block"); csi vs host volume config confusion; older configs using values valid only for CSI plugin volumes.

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/4e522bc1294de1d8. Report an issue: GitHub.